librus-python-api 1.0.3__py3-none-any.whl → 1.2.1__py3-none-any.whl

librus_python_api/__init__.py

@@ -65,6 +65,9 @@ from librus_python_api.models import (
     MessageTimestamp,
     MessagingBackend,
     ModernAccountData,
+    ModernCorrespondent,
+    ModernCorrespondentReference,
+    ModernCorrespondents,
     ModernIdentity,
     ModernMessageAttachment,
     ModernMessageAttachmentReference,
@@ -82,6 +85,10 @@ from librus_python_api.models import (
     ModernRecipientTypeReference,
     ModernRecipientTypes,
     ModernSendSubmission,
+    ModernTeacherSubject,
+    ModernTeacherSubjects,
+    ModernUnreadCounts,
+    ModernUnreadFolders,
     NotificationCategory,
     NotificationCount,
     NotificationCounts,
@@ -120,7 +127,7 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.0.3"
+__version__ = "1.2.1"
 
 __all__ = [
     "AccountContext",
@@ -135,6 +142,13 @@ __all__ = [
     "ModernMessageRecipientReceipt",
     "ModernMessages",
     "ModernMessagesCursor",
+    "ModernUnreadCounts",
+    "ModernCorrespondent",
+    "ModernCorrespondentReference",
+    "ModernCorrespondents",
+    "ModernTeacherSubject",
+    "ModernTeacherSubjects",
+    "ModernUnreadFolders",
     "ModernMessagesPage",
     "ModernMessageSummary",
     "ModernRecipient",

librus_python_api/config.py

@@ -207,6 +207,60 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 Evidence.INDEPENDENTLY_OBSERVED,
                 "messages",
             ),
+            Endpoint(
+                "modern_archive_messages_received",
+                "GET",
+                "/api/archive/inbox/messages",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_archive_messages_sent",
+                "GET",
+                "/api/archive/outbox/messages",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_unread_counts",
+                "GET",
+                "/api/inbox/unreadMessagesCount",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_senders",
+                "GET",
+                "/api/inbox/messages/senders",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_receivers",
+                "GET",
+                "/api/outbox/messages/receivers",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
+            Endpoint(
+                "modern_teacher_subjects",
+                "GET",
+                "/api/receivers/student-subjects",
+                SideEffect.NONE,
+                False,
+                Evidence.INDEPENDENTLY_OBSERVED,
+                "messages",
+            ),
             Endpoint(
                 "modern_content_received",
                 "GET",
@@ -878,17 +932,67 @@ def modern_directory_query(
 
 
 def modern_mailbox_query(
-    folder: MessageFolder, page: int, page_size: int
+    folder: MessageFolder,
+    page: int,
+    page_size: int,
+    *,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> dict[str, str]:
+    """Page selection plus the web app's own sender/receiver/unread filters."""
     if (
         not isinstance(folder, MessageFolder)
         or type(page) is not int
         or not 1 <= page <= 1000
         or type(page_size) is not int
         or not 1 <= page_size <= 50
+        or type(unread_only) is not bool
+        or (unread_only and folder is not MessageFolder.RECEIVED)
+        or (
+            correspondent is not None
+            and (
+                type(correspondent) is not str
+                or re.fullmatch(r"[0-9]{1,64}", correspondent) is None
+            )
+        )
     ):
         raise LibrusError(ErrorKind.INVALID_INPUT)
-    return {"page": str(page), "limit": str(page_size)}
+    query = {}
+    if correspondent is not None:
+        query[MODERN_CORRESPONDENT_FILTERS[folder]] = correspondent
+    if unread_only:
+        query["unreadOnly"] = "1"
+    return query | {"page": str(page), "limit": str(page_size)}
+
+
+MODERN_MAILBOX_OPERATIONS = frozenset(
+    {
+        "modern_messages_received",
+        "modern_messages_sent",
+        "modern_archive_messages_received",
+        "modern_archive_messages_sent",
+    }
+)
+MODERN_CORRESPONDENT_FILTERS = MappingProxyType(
+    {MessageFolder.RECEIVED: "senderId", MessageFolder.SENT: "receiverId"}
+)
+# Filters observed in the web app for the current mailbox only.
+MODERN_MAILBOX_FILTERS = MappingProxyType(
+    {
+        "modern_messages_received": frozenset({"senderId", "unreadOnly"}),
+        "modern_messages_sent": frozenset({"receiverId"}),
+    }
+)
+MODERN_UNREAD_COUNT_FIELDS = (
+    "inbox",
+    "notes",
+    "alerts",
+    "substitutions",
+    "absences",
+    "justifications",
+    "trash",
+)
+MODERN_MAX_UNREAD_COUNT = 1000000
 
 
 def validate_modern_query(operation: str, query: Mapping[str, str]) -> None:
@@ -897,14 +1001,27 @@ def validate_modern_query(operation: str, query: Mapping[str, str]) -> None:
         type(v) is not str for v in query.values()
     ):
         raise LibrusError(ErrorKind.INVALID_INPUT)
-    if operation in {"modern_messages_received", "modern_messages_sent"}:
-        if set(query) != {"page", "limit"} or any(
+    if operation in MODERN_MAILBOX_OPERATIONS:
+        filters = MODERN_MAILBOX_FILTERS.get(operation, frozenset())
+        if not {"page", "limit"} <= set(query) <= {"page", "limit"} | filters or any(
             re.fullmatch(r"[1-9][0-9]{0,3}", query[name]) is None
             for name in ("page", "limit")
         ):
             raise LibrusError(ErrorKind.INVALID_INPUT)
+        folder = (
+            MessageFolder.SENT
+            if operation == "modern_messages_sent"
+            else MessageFolder.RECEIVED
+        )
+        unread = query.get("unreadOnly")
+        if unread not in (None, "1"):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
         modern_mailbox_query(
-            MessageFolder.RECEIVED, int(query["page"]), int(query["limit"])
+            folder,
+            int(query["page"]),
+            int(query["limit"]),
+            correspondent=query.get(MODERN_CORRESPONDENT_FILTERS[folder]),
+            unread_only=unread == "1",
         )
         return
     allowed = [

librus_python_api/models.py

@@ -48,6 +48,12 @@ type OperationName = Literal[
     "modern_send_message",
     "modern_school_recipients",
     "modern_class_parents",
+    "modern_archive_messages_received",
+    "modern_archive_messages_sent",
+    "modern_unread_counts",
+    "modern_senders",
+    "modern_receivers",
+    "modern_teacher_subjects",
     "modern_messages_received",
     "modern_messages_sent",
     "modern_content_received",
@@ -393,6 +399,46 @@ class ModernMessageReference:
     folder: MessageFolder
     identifier: str = field(repr=False)
     account: str = field(repr=False)
+    # Listed from the archive mailbox. Archived content opens are not supported.
+    archived: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ModernCorrespondentReference:
+    """A sender (received folder) or receiver (sent folder) to filter a list by."""
+
+    folder: MessageFolder
+    identifier: str = field(repr=False)
+    account: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ModernCorrespondent:
+    reference: ModernCorrespondentReference = field(repr=False)
+    first_name: str = field(repr=False)
+    last_name: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ModernCorrespondents:
+    identity: "Identity" = field(repr=False)
+    folder: MessageFolder
+    items: tuple[ModernCorrespondent, ...] = field(repr=False)
+    observation: "Observation"
+
+
+@dataclass(frozen=True, slots=True)
+class ModernTeacherSubject:
+    # The teacher's modern account ID, as a decimal string.
+    teacher_identifier: str = field(repr=False)
+    subject: str = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ModernTeacherSubjects:
+    identity: "Identity" = field(repr=False)
+    items: tuple[ModernTeacherSubject, ...] = field(repr=False)
+    observation: "Observation"
 
 
 @dataclass(frozen=True, slots=True)
@@ -417,6 +463,11 @@ class ModernMessagesPage:
     items: tuple[ModernMessageSummary, ...] = field(repr=False)
     fingerprint: str = field(repr=False)
     observation: "Observation"
+    archived: bool = False
+    correspondent: ModernCorrespondentReference | None = field(default=None, repr=False)
+    unread_only: bool = False
+    # Archive listings only: the upstream archivingInProgress status flag.
+    archiving_in_progress: bool | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -429,6 +480,9 @@ class ModernMessagesCursor:
     total_count: int
     fingerprint: str = field(repr=False)
     seen_ids: tuple[str, ...] = field(repr=False)
+    archived: bool = False
+    correspondent: str | None = field(default=None, repr=False)
+    unread_only: bool = False
 
 
 @dataclass(frozen=True, slots=True)
@@ -441,6 +495,32 @@ class ModernMessages:
     next_cursor: ModernMessagesCursor | None = field(repr=False)
     truncation_reason: Literal["item_limit", "page_limit"] | None
     observation: "Observation"
+    archived: bool = False
+    correspondent: ModernCorrespondentReference | None = field(default=None, repr=False)
+    unread_only: bool = False
+    # Archive listings only: the upstream archivingInProgress status flag.
+    archiving_in_progress: bool | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModernUnreadFolders:
+    """Unread counters the modern mailbox shows for one mailbox section."""
+
+    inbox: int
+    notes: int
+    alerts: int
+    substitutions: int
+    absences: int
+    justifications: int
+    trash: int
+
+
+@dataclass(frozen=True, slots=True)
+class ModernUnreadCounts:
+    identity: "Identity" = field(repr=False)
+    current: ModernUnreadFolders
+    archive: ModernUnreadFolders
+    observation: "Observation"
 
 
 @dataclass(frozen=True, slots=True)

librus_python_api/modern_mailbox.py

@@ -14,11 +14,17 @@ from librus_python_api.config import (
     MESSAGE_MAX_CURSOR_IDS,
     MESSAGE_MAX_FIELD_LENGTH,
     MESSAGE_MAX_TOTAL_TEXT_LENGTH,
+    MODERN_MAX_LABEL,
+    MODERN_MAX_RECIPIENTS,
+    MODERN_MAX_UNREAD_COUNT,
+    MODERN_UNREAD_COUNT_FIELDS,
     modern_mailbox_query,
 )
 from librus_python_api.exceptions import ErrorKind, LibrusError
 from librus_python_api.models import (
     MessageFolder,
+    ModernCorrespondent,
+    ModernCorrespondentReference,
     ModernMessageAttachment,
     ModernMessageAttachmentReference,
     ModernMessageRecipientReceipt,
@@ -26,6 +32,7 @@ from librus_python_api.models import (
     ModernMessagesCursor,
     ModernMessagesPage,
     ModernMessageSummary,
+    ModernUnreadFolders,
 )
 from librus_python_api.modern_body import render_body
 from librus_python_api.parsers import decode_json
@@ -48,6 +55,7 @@ def validate_reference(reference: ModernMessageReference, account: str) -> None:
         not isinstance(reference, ModernMessageReference)
         or not isinstance(reference.folder, MessageFolder)
         or reference.account != account
+        or type(reference.archived) is not bool
         or type(reference.identifier) is not str
         or re.fullmatch(r"[0-9]{1,64}", reference.identifier) is None
     ):
@@ -75,7 +83,9 @@ def _date(value: Any) -> datetime:
     raise LibrusError(ErrorKind.PARSE)
 
 
-def _summary(data: Any, folder: MessageFolder, account: str) -> ModernMessageSummary:
+def _summary(
+    data: Any, folder: MessageFolder, account: str, archived: bool
+) -> ModernMessageSummary:
     if not isinstance(data, dict):
         raise LibrusError(ErrorKind.PARSE)
     correspondent = (
@@ -98,7 +108,9 @@ def _summary(data: Any, folder: MessageFolder, account: str) -> ModernMessageSum
     read = data.get("readDate")
     read_at = None if read in (None, "") else _date(read)
     return ModernMessageSummary(
-        ModernMessageReference(folder, identifier(data.get("messageId")), account),
+        ModernMessageReference(
+            folder, identifier(data.get("messageId")), account, archived
+        ),
         name,
         subject,
         _date(stamp),
@@ -110,13 +122,23 @@ def _summary(data: Any, folder: MessageFolder, account: str) -> ModernMessageSum
 
 
 def parse_page(
-    body: bytes, folder: MessageFolder, page: int, page_size: int, account: str
-) -> tuple[tuple[ModernMessageSummary, ...], int, str]:
+    body: bytes,
+    folder: MessageFolder,
+    page: int,
+    page_size: int,
+    account: str,
+    archived: bool = False,
+) -> tuple[tuple[ModernMessageSummary, ...], int, str, bool | None]:
     modern_mailbox_query(folder, page, page_size)
     data = decode_json(body)
     if not isinstance(data, dict) or not {"data", "total"} <= set(data):
         raise LibrusError(ErrorKind.PARSE)
-    if data.get("archivingInProgress", False) is not False:
+    in_progress = data.get("archivingInProgress", False)
+    if type(in_progress) is not bool:
+        raise LibrusError(ErrorKind.PARSE)
+    # Live archive pages report true while listing normally; it is a status
+    # flag there. The current mailbox has never shown it.
+    if in_progress and not archived:
         raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
     entries, total = data["data"], data["total"]
     if (
@@ -130,7 +152,7 @@ def parse_page(
     expected = min(page_size, max(0, total - (page - 1) * page_size))
     if len(entries) != expected:
         raise LibrusError(ErrorKind.PARSE)
-    items = tuple(_summary(item, folder, account) for item in entries)
+    items = tuple(_summary(item, folder, account, archived) for item in entries)
     if len({item.reference.identifier for item in items}) != len(items):
         raise LibrusError(ErrorKind.PARSE)
     if (
@@ -155,7 +177,7 @@ def parse_page(
             )
         ).encode()
     ).hexdigest()
-    return items, total, fingerprint
+    return items, total, fingerprint, in_progress if archived else None
 
 
 @dataclass(frozen=True, slots=True, repr=False)
@@ -280,6 +302,7 @@ def parse_content(body: bytes, reference: ModernMessageReference) -> ParsedConte
         content | {"isAnyFileAttached": has_attachment},
         reference.folder,
         reference.account,
+        reference.archived,
     )
     if summary.reference != reference:
         raise LibrusError(ErrorKind.PARSE)
@@ -326,8 +349,15 @@ def validate_selection(
     max_pages: int,
     limit: int,
     account: str,
+    archived: bool = False,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> None:
-    modern_mailbox_query(folder, 1, page_size)
+    modern_mailbox_query(
+        folder, 1, page_size, correspondent=correspondent, unread_only=unread_only
+    )
+    if type(archived) is not bool:
+        raise LibrusError(ErrorKind.INVALID_INPUT)
     if type(max_pages) is not int or not 1 <= max_pages <= MESSAGE_MAX_BATCH_PAGES:
         raise LibrusError(ErrorKind.INVALID_INPUT)
     if type(limit) is not int or not 1 <= limit <= MESSAGE_MAX_BATCH_ITEMS:
@@ -340,6 +370,9 @@ def validate_selection(
     if (
         cursor.account != account
         or cursor.folder is not folder
+        or cursor.archived is not archived
+        or cursor.correspondent != correspondent
+        or cursor.unread_only is not unread_only
         or cursor.page_size != page_size
         or type(cursor.offset) is not int
         or not 0 <= cursor.offset < page_size
@@ -367,6 +400,9 @@ async def collect(
     page_size: int,
     max_pages: int,
     limit: int,
+    archived: bool = False,
+    correspondent: str | None = None,
+    unread_only: bool = False,
 ) -> tuple[
     tuple[ModernMessageSummary, ...],
     int,
@@ -374,7 +410,17 @@ async def collect(
     ModernMessagesCursor | None,
     Literal["item_limit", "page_limit"] | None,
 ]:
-    validate_selection(folder, cursor, page_size, max_pages, limit, account)
+    validate_selection(
+        folder,
+        cursor,
+        page_size,
+        max_pages,
+        limit,
+        account,
+        archived,
+        correspondent,
+        unread_only,
+    )
     page = cursor.page if cursor else 1
     offset = cursor.offset if cursor else 0
     seen = list(cursor.seen_ids) if cursor else []
@@ -427,6 +473,9 @@ async def collect(
                         total,
                         result.fingerprint,
                         tuple(seen),
+                        archived,
+                        correspondent,
+                        unread_only,
                     ),
                     "item_limit",
                 )
@@ -452,8 +501,87 @@ async def collect(
                     total,
                     result.fingerprint,
                     tuple(seen),
+                    archived,
+                    correspondent,
+                    unread_only,
                 ),
                 "item_limit" if len(items) >= limit else "page_limit",
             )
         page, offset = page + 1, 0
     raise AssertionError("Bounded collector must terminate")
+
+
+def _unread_folders(data: dict[str, Any], prefix: str) -> ModernUnreadFolders:
+    values = []
+    for name in MODERN_UNREAD_COUNT_FIELDS:
+        key = prefix + name[0].upper() + name[1:] if prefix else name
+        value = data.get(key)
+        if type(value) is not int or value < 0:
+            raise LibrusError(ErrorKind.PARSE)
+        if value > MODERN_MAX_UNREAD_COUNT:
+            raise LibrusError(ErrorKind.LIMIT)
+        values.append(value)
+    return ModernUnreadFolders(*values)
+
+
+def parse_unread_counts(
+    body: bytes,
+) -> tuple[ModernUnreadFolders, ModernUnreadFolders]:
+    """Current and archive counters; unknown extra counters stay inert."""
+    data = decode_json(body)
+    counts = data.get("data") if isinstance(data, dict) else None
+    if not isinstance(counts, dict):
+        raise LibrusError(ErrorKind.PARSE)
+    return _unread_folders(counts, ""), _unread_folders(counts, "archive")
+
+
+def validate_correspondent(
+    reference: ModernCorrespondentReference | None, folder: MessageFolder, account: str
+) -> str | None:
+    """The filter value for a correspondent listed for this folder and login."""
+    if reference is None:
+        return None
+    if (
+        not isinstance(reference, ModernCorrespondentReference)
+        or reference.folder is not folder
+        or reference.account != account
+        or type(reference.identifier) is not str
+        or re.fullmatch(r"[0-9]{1,64}", reference.identifier) is None
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    return reference.identifier
+
+
+def _name(value: Any) -> str:
+    if type(value) is not str or len(value) > MODERN_MAX_LABEL or "\x00" in value:
+        raise LibrusError(ErrorKind.PARSE)
+    return value
+
+
+def parse_correspondents(
+    body: bytes, folder: MessageFolder, account: str
+) -> tuple[ModernCorrespondent, ...]:
+    """People the folder's messages came from (received) or went to (sent)."""
+    role = "sender" if folder is MessageFolder.RECEIVED else "receiver"
+    data = decode_json(body)
+    entries = data.get("data") if isinstance(data, dict) else None
+    if not isinstance(entries, list):
+        raise LibrusError(ErrorKind.PARSE)
+    if len(entries) > MODERN_MAX_RECIPIENTS:
+        raise LibrusError(ErrorKind.LIMIT)
+    items = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise LibrusError(ErrorKind.PARSE)
+        first = _name(entry.get(f"{role}FirstName"))
+        last = _name(entry.get(f"{role}LastName"))
+        # Institutional senders can carry a single name part; never both empty.
+        if not (first.strip() or last.strip()):
+            raise LibrusError(ErrorKind.PARSE)
+        reference = ModernCorrespondentReference(
+            folder, identifier(entry.get(f"{role}Id")), account
+        )
+        items.append(ModernCorrespondent(reference, first, last))
+    if len({item.reference.identifier for item in items}) != len(items):
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(items)

librus_python_api/modern_messages.py

@@ -23,6 +23,7 @@ from librus_python_api.models import (
     ModernRecipientReference,
     ModernRecipientType,
     ModernRecipientTypeReference,
+    ModernTeacherSubject,
     SendStatus,
 )
 from librus_python_api.parsers import decode_json
@@ -274,3 +275,25 @@ def parse_modern_send_response(body: bytes, status: int) -> SendStatus:
         ):
             return SendStatus.REJECTED
     raise LibrusError(ErrorKind.UNKNOWN_DELIVERY)
+
+
+def parse_teacher_subjects(body: bytes) -> tuple[ModernTeacherSubject, ...]:
+    """Teacher account IDs paired with the subjects they teach the student."""
+    entries = _object(decode_json(body)).get("data")
+    if not isinstance(entries, list):
+        raise LibrusError(ErrorKind.PARSE)
+    if len(entries) > MODERN_MAX_RECIPIENTS:
+        raise LibrusError(ErrorKind.LIMIT)
+    items = []
+    for entry in entries:
+        value = _object(entry)
+        raw = value.get("teacherIdentifier")
+        if type(raw) is int and 0 < raw < 10**64:
+            raw = str(raw)
+        item = ModernTeacherSubject(_identifier(raw), _label(value.get("subject")))
+        # Live lists can repeat an identical pair; the copy adds nothing.
+        if item not in items:
+            items.append(item)
+    if sum(len(item.subject) for item in items) > MODERN_MAX_TOTAL_TEXT:
+        raise LibrusError(ErrorKind.LIMIT)
+    return tuple(items)

librus_python_api/service.py

@@ -107,6 +107,8 @@ from librus_python_api.models import (
     MessagesPage,
     MessageSummary,
     ModernAccountData,
+    ModernCorrespondentReference,
+    ModernCorrespondents,
     ModernIdentity,
     ModernMessageAttachmentReference,
     ModernMessageContent,
@@ -119,6 +121,8 @@ from librus_python_api.models import (
     ModernRecipientTypeReference,
     ModernRecipientTypes,
     ModernSendSubmission,
+    ModernTeacherSubjects,
+    ModernUnreadCounts,
     NotificationCounts,
     Observation,
     OperationName,
@@ -146,7 +150,16 @@ from librus_python_api.modern_mailbox import collect as collect_modern_messages
 from librus_python_api.modern_mailbox import (
     parse_content as parse_modern_message_content,
 )
+from librus_python_api.modern_mailbox import (
+    parse_correspondents as parse_modern_correspondents,
+)
 from librus_python_api.modern_mailbox import parse_page as parse_modern_message_page
+from librus_python_api.modern_mailbox import (
+    parse_unread_counts as parse_modern_unread_counts,
+)
+from librus_python_api.modern_mailbox import (
+    validate_correspondent as validate_modern_correspondent,
+)
 from librus_python_api.modern_mailbox import (
     validate_reference as validate_modern_message_reference,
 )
@@ -160,6 +173,9 @@ from librus_python_api.modern_messages import (
     parse_modern_types,
     validate_modern_type,
 )
+from librus_python_api.modern_messages import (
+    parse_teacher_subjects as parse_modern_teacher_subjects,
+)
 from librus_python_api.notifications import (
     decode_payload,
     parse_notification_counts,
@@ -590,21 +606,32 @@ class AccountClient:
         )
 
     async def _modern_message_page(
-        self, folder: MessageFolder, page: int, page_size: int, budget: RequestBudget
+        self,
+        folder: MessageFolder,
+        page: int,
+        page_size: int,
+        budget: RequestBudget,
+        archived: bool,
+        correspondent: ModernCorrespondentReference | None = None,
+        unread_only: bool = False,
     ) -> ModernMessagesPage:
-        operation: Literal["modern_messages_received", "modern_messages_sent"] = (
-            "modern_messages_received"
-            if folder is MessageFolder.RECEIVED
-            else "modern_messages_sent"
-        )
-        items, total, fingerprint = await self._page(
+        operation = _modern_mailbox_operation(folder, archived)
+        items, total, fingerprint, in_progress = await self._page(
             operation,
             budget,
             lambda body: parse_modern_message_page(
-                body, folder, page, page_size, self._alias
+                body, folder, page, page_size, self._alias, archived
             ),
             content_type=JSON,
-            query=modern_mailbox_query(folder, page, page_size),
+            query=modern_mailbox_query(
+                folder,
+                page,
+                page_size,
+                correspondent=None
+                if correspondent is None
+                else correspondent.identifier,
+                unread_only=unread_only,
+            ),
         )
         return ModernMessagesPage(
             self._session_identity(),
@@ -615,31 +642,62 @@ class AccountClient:
             items,
             fingerprint,
             self._observation(operation),
+            archived,
+            correspondent,
+            unread_only,
+            in_progress,
         )
 
+    def _modern_filter(
+        self,
+        folder: MessageFolder,
+        archived: bool,
+        correspondent: ModernCorrespondentReference | None,
+        unread_only: bool,
+    ) -> str | None:
+        """Validate list filters; they are observed for the current mailbox only."""
+        value = validate_modern_correspondent(correspondent, folder, self._alias)
+        if type(archived) is not bool or type(unread_only) is not bool:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        if unread_only and folder is not MessageFolder.RECEIVED:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        if archived and (value is not None or unread_only):
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        return value
+
     async def modern_messages_page(
         self,
         folder: MessageFolder = MessageFolder.RECEIVED,
         *,
         page: int = 1,
         page_size: int = 10,
+        archived: bool = False,
+        correspondent: ModernCorrespondentReference | None = None,
+        unread_only: bool = False,
         budget: RequestBudget | None = None,
         max_age_seconds: float = 0.0,
     ) -> ModernMessagesPage:
-        """One one-based ordinary modern page, without any content open."""
+        """One one-based ordinary modern page, without any content open.
+
+        ``archived`` lists the archive mailbox (earlier school years) instead.
+        ``correspondent`` (from ``modern_correspondents``) and ``unread_only``
+        (received folder) filter the current mailbox as the web app does.
+        """
         modern_mailbox_query(folder, page, page_size)
-        operation: Literal["modern_messages_received", "modern_messages_sent"] = (
-            "modern_messages_received"
-            if folder is MessageFolder.RECEIVED
-            else "modern_messages_sent"
-        )
+        filter_id = self._modern_filter(folder, archived, correspondent, unread_only)
+        operation = _modern_mailbox_operation(folder, archived)
 
         async def fetch(budget: RequestBudget, _: bool) -> ModernMessagesPage:
             await self._modern_ready(budget)
-            return await self._modern_message_page(folder, page, page_size, budget)
+            return await self._modern_message_page(
+                folder, page, page_size, budget, archived, correspondent, unread_only
+            )
 
         return await self._read(
-            (operation, "page", page, page_size), fetch, budget, max_age_seconds
+            (operation, "page", page, page_size, filter_id, unread_only),
+            fetch,
+            budget,
+            max_age_seconds,
         )
 
     async def modern_messages(
@@ -650,29 +708,55 @@ class AccountClient:
         page_size: int = 50,
         max_pages: int = 4,
         limit: int = 128,
+        archived: bool = False,
+        correspondent: ModernCorrespondentReference | None = None,
+        unread_only: bool = False,
         budget: RequestBudget | None = None,
         max_age_seconds: float = 0.0,
     ) -> ModernMessages:
         """Bounded modern collection with selection-bound continuation."""
+        filter_id = self._modern_filter(folder, archived, correspondent, unread_only)
         validate_modern_message_selection(
-            folder, cursor, page_size, max_pages, limit, self._alias
-        )
-        operation: Literal["modern_messages_received", "modern_messages_sent"] = (
-            "modern_messages_received"
-            if folder is MessageFolder.RECEIVED
-            else "modern_messages_sent"
+            folder,
+            cursor,
+            page_size,
+            max_pages,
+            limit,
+            self._alias,
+            archived,
+            filter_id,
+            unread_only,
         )
+        operation = _modern_mailbox_operation(folder, archived)
 
         async def fetch(budget: RequestBudget, _: bool) -> ModernMessages:
             await self._modern_ready(budget)
+            flags: list[bool | None] = []
+
+            async def page_of(page: int) -> ModernMessagesPage:
+                result = await self._modern_message_page(
+                    folder,
+                    page,
+                    page_size,
+                    budget,
+                    archived,
+                    correspondent,
+                    unread_only,
+                )
+                flags.append(result.archiving_in_progress)
+                return result
+
             result = await collect_modern_messages(
-                lambda page: self._modern_message_page(folder, page, page_size, budget),
+                page_of,
                 folder,
                 self._alias,
                 cursor,
                 page_size,
                 max_pages,
                 limit,
+                archived,
+                filter_id,
+                unread_only,
             )
             items, pages, duplicates, continuation, reason = result
             return ModernMessages(
@@ -684,15 +768,106 @@ class AccountClient:
                 continuation,
                 reason,
                 self._observation(operation),
+                archived,
+                correspondent,
+                unread_only,
+                any(flags) if archived else None,
             )
 
         return await self._read(
-            (operation, "batch", cursor, page_size, max_pages, limit),
+            (
+                operation,
+                "batch",
+                cursor,
+                page_size,
+                max_pages,
+                limit,
+                filter_id,
+                unread_only,
+            ),
             fetch,
             budget,
             max_age_seconds,
         )
 
+    async def modern_correspondents(
+        self,
+        folder: MessageFolder = MessageFolder.RECEIVED,
+        *,
+        budget: RequestBudget | None = None,
+        max_age_seconds: float = 0.0,
+    ) -> ModernCorrespondents:
+        """Senders (received) or receivers (sent) the current mailbox can filter by."""
+        if not isinstance(folder, MessageFolder):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        operation: Literal["modern_senders", "modern_receivers"] = (
+            "modern_senders" if folder is MessageFolder.RECEIVED else "modern_receivers"
+        )
+
+        async def fetch(budget: RequestBudget, _: bool) -> ModernCorrespondents:
+            await self._modern_ready(budget)
+            items = await self._page(
+                operation,
+                budget,
+                lambda body: parse_modern_correspondents(body, folder, self._alias),
+                content_type=JSON,
+            )
+            return ModernCorrespondents(
+                self._session_identity(),
+                folder,
+                items,
+                self._observation(operation),
+            )
+
+        return await self._read((operation,), fetch, budget, max_age_seconds)
+
+    async def modern_teacher_subjects(
+        self, *, budget: RequestBudget | None = None, max_age_seconds: float = 0.0
+    ) -> ModernTeacherSubjects:
+        """Teachers' modern account IDs with the subjects they teach the student."""
+
+        async def fetch(budget: RequestBudget, _: bool) -> ModernTeacherSubjects:
+            await self._modern_ready(budget)
+            items = await self._page(
+                "modern_teacher_subjects",
+                budget,
+                parse_modern_teacher_subjects,
+                content_type=JSON,
+            )
+            return ModernTeacherSubjects(
+                self._session_identity(),
+                items,
+                self._observation("modern_teacher_subjects"),
+            )
+
+        return await self._read(
+            ("modern_teacher_subjects",), fetch, budget, max_age_seconds
+        )
+
+    async def modern_unread_counts(
+        self, *, budget: RequestBudget | None = None, max_age_seconds: float = 0.0
+    ) -> ModernUnreadCounts:
+        """Unread counters of the modern mailbox, without opening any message."""
+
+        async def fetch(budget: RequestBudget, _: bool) -> ModernUnreadCounts:
+            await self._modern_ready(budget)
+            current, archive = await self._page(
+                "modern_unread_counts",
+                budget,
+                parse_modern_unread_counts,
+                content_type=JSON,
+            )
+            return ModernUnreadCounts(
+                self._session_identity(),
+                current,
+                archive,
+                self._observation("modern_unread_counts"),
+            )
+
+        return await self._read(
+            ("modern_unread_counts",), fetch, budget, max_age_seconds
+        )
+
     async def modern_message_content(
         self,
         reference: ModernMessageReference,
@@ -706,6 +881,9 @@ class AccountClient:
             reference.folder is MessageFolder.RECEIVED and not allow_mark_read
         ):
             raise LibrusError(ErrorKind.INVALID_INPUT)
+        if reference.archived:
+            # No archived content route or mark-read effect is established yet.
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
         operation: Literal["modern_content_received", "modern_content_sent"] = (
             "modern_content_received"
             if reference.folder is MessageFolder.RECEIVED
@@ -2336,5 +2514,20 @@ class AccountClient:
         return response
 
 
+def _modern_mailbox_operation(
+    folder: MessageFolder, archived: bool
+) -> Literal[
+    "modern_messages_received",
+    "modern_messages_sent",
+    "modern_archive_messages_received",
+    "modern_archive_messages_sent",
+]:
+    if folder is MessageFolder.RECEIVED:
+        if archived:
+            return "modern_archive_messages_received"
+        return "modern_messages_received"
+    return "modern_archive_messages_sent" if archived else "modern_messages_sent"
+
+
 def _media_type(response: TransportResponse) -> str:
     return response.headers.get("content-type", "").partition(";")[0].strip().lower()

librus_python_api/transport.py

@@ -34,6 +34,7 @@ from librus_python_api.config import (
     MESSAGE_PAGE_FIELDS,
     MODERN_DIRECTORY_QUERIES,
     MODERN_HANDOFF_PATTERN,
+    MODERN_MAILBOX_OPERATIONS,
     MODERN_TERMINAL_PATHS,
     OAUTH_QUERY,
     USER_AGENT,
@@ -297,12 +298,8 @@ class AiohttpTransport:
             url = str(URL(url).with_query(MODERN_DIRECTORY_QUERIES[endpoint_id]))
         if (
             endpoint_id
-            in {
-                "modern_school_recipients",
-                "modern_class_parents",
-                "modern_messages_received",
-                "modern_messages_sent",
-            }
+            in {"modern_school_recipients", "modern_class_parents"}
+            | MODERN_MAILBOX_OPERATIONS
             and query is None
         ):
             raise LibrusError(ErrorKind.INVALID_INPUT)

{librus_python_api-1.0.3.dist-info → librus_python_api-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.0.3
+Version: 1.2.1
 Summary: Independent bounded async Librus Synergia client
 Project-URL: Repository, https://github.com/krzysztofbury/librus-python-api
 Project-URL: Issues, https://github.com/krzysztofbury/librus-python-api/issues
@@ -51,7 +51,7 @@ See [limitations](#supported-features-and-limitations) below.
 Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.3
+python -m pip install librus-python-api==1.2.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -67,7 +67,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.3-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.2.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.

{librus_python_api-1.0.3.dist-info → librus_python_api-1.2.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-librus_python_api/__init__.py,sha256=6WrjdwyywtqZ9iRD7jGBvGjOdy7YAAUNfChbcT4jdQU,5657
+librus_python_api/__init__.py,sha256=cFnpyZw2vPzTFefw3pbhiP3f-CvFABI4rnGdpLye-LQ,6045
 librus_python_api/_notification_bootstrap.py,sha256=18nzH0doXBNaZXCz-_ckIvRrlHTWV5Mm1t5m2-5eYGI,4669
 librus_python_api/_notification_codec.py,sha256=hU6G3zGJ5fR8wfPC6fV2OqBKs-7XpT9eRnKO3FGsTzY,13451
 librus_python_api/_storage.py,sha256=M_6ZAzN4zs7laOdKJBRH1I2rvy3pgqYgC_MZtsd2xtM,15893
@@ -11,7 +11,7 @@ librus_python_api/attendance_frequency.py,sha256=SBhED5zuyRIHWdw4urFyTJYykb6EYB7
 librus_python_api/budget.py,sha256=8fvqT7eIxyVX2P2OBG27XsYHk_HbtSS4lzuecYpHtgs,2878
 librus_python_api/checkpoint.py,sha256=QBmG9GtpyaGRaFq-FXuGA3yR1BjuMFN9V3RTvvi_FNQ,1930
 librus_python_api/completed_lessons.py,sha256=sR2oLSGb2q1580l-2upCBv9sQfIcHi7CQfWr1K0EFXI,7635
-librus_python_api/config.py,sha256=Tx104USrajcwJe9SxfJWK6ppeoSYqd88lC_PKsCJMYs,49575
+librus_python_api/config.py,sha256=43tAalNG8_Em7Q-lXs1nmX-GKw7333CKpNAvJtGMg4E,53193
 librus_python_api/detail_fields.py,sha256=K10Stx_ehDTttkUI7-G7a2Ko9exYEu5NJpR-3sBnQ60,1789
 librus_python_api/diagnostics.py,sha256=2l7wq6RA3it-Gwj-JRLcw5qbI37fl3xII6GZA2mZj0o,856
 librus_python_api/exceptions.py,sha256=yWWoo0xyrQAk1d13HOJZnQBsq4ulh_P0hRSI6ZiNQOE,4622
@@ -23,10 +23,10 @@ librus_python_api/lifecycle.py,sha256=XzA5CEdZFo7iL5IMUrawnRvf2m9BFe0OseP-fpQFaA
 librus_python_api/markup.py,sha256=GZk7MmBBGB5SIVY_VngmQxQErI3eGHOpJs3mFVlMR3M,5298
 librus_python_api/message_content.py,sha256=sUPuqpjuavqDyn6QGM5aPH4mpoQV62bDLepSSQ2AsUE,8686
 librus_python_api/messages.py,sha256=K9F8XVs1SojfFpdxxLV8gx9E0g81YxEHjigDzLHmDCg,10230
-librus_python_api/models.py,sha256=aGPst3eV44w4YB-0HbmskumDz-KAHekTf6J6_CHaRbE,33826
+librus_python_api/models.py,sha256=vqoQAL1IMgnOHRlNWxchMiOdkw7AnYDnyiYEQ2OAHko,36363
 librus_python_api/modern_body.py,sha256=3L4P_cIrHdIxZqiinFSQrDMhG6iklT1GoA-VEWMJUiI,2682
-librus_python_api/modern_mailbox.py,sha256=nRrmIHb7RfV49xjUTBlDcgtxOdmXEpp4F1L0IvcGQxw,16118
-librus_python_api/modern_messages.py,sha256=9gysqjUkQGtMKmnCL7boRzNDnAhtL5ibAJ2rkNZWCec,9694
+librus_python_api/modern_mailbox.py,sha256=2jF9UnJZ5AF6dip-GrMcv_z2kSLpp87dIpVeXk9jMzA,20600
+librus_python_api/modern_messages.py,sha256=qt2CXtrxCZQ-jTt0aQCD6ZaPAJQZXf0BxmvacPo9B0w,10653
 librus_python_api/notification_models.py,sha256=4eLTAE9JzHhveoaWtZQwGBolmb87QUP5kOSW7Jjt7J0,4199
 librus_python_api/notification_persistence.py,sha256=hXKmzAh0yNYG_n5CLlZOcoYOZdQnlrSeNtjjXiDmLm4,49532
 librus_python_api/notification_workflow.py,sha256=MsBJdwn6J1UUGlz3Ldzi7WEBz5Qsama7eGmZvUQj25g,12924
@@ -39,10 +39,10 @@ librus_python_api/recipients.py,sha256=6GQCKo-Zjg3VFSg1J8YXcDsy_U3r6-MUS4VCvz0xd
 librus_python_api/scheduler.py,sha256=3JplYxqvQdFz3aKXcoQUJHE9s3FPw_xRhQ2CPNLuQmA,10729
 librus_python_api/school_reads.py,sha256=PCnZ4lv44j-68FgJpQiMteaPSyfhbX8_3CUyE6zhFcQ,14760
 librus_python_api/sending.py,sha256=Nvvk2r-6D6Us53a2fH5GW9PcA6bWEfuOvy6c3M5QVcE,4549
-librus_python_api/service.py,sha256=tTjOC3nOWQL1O7QH-IvoSukJX7oNENmAN5xH8z-d8a0,86557
+librus_python_api/service.py,sha256=1hQkDjEIlOwF5_4aSAEkmb1iMdUU51bVyPTVc7BAKJU,93252
 librus_python_api/timetable.py,sha256=tX1QK9fQABxzfLaHHqTe8e6rAgdOkCoTOfAHdPwNmLE,9836
-librus_python_api/transport.py,sha256=6S5wwBiRkUfKmi6w2t8msxlTSzCo-IbIBE13FeBc7Jw,35357
-librus_python_api-1.0.3.dist-info/METADATA,sha256=PbL-qr7wfo185OJS5JpIWHdli4xxck8uOtVRVuVHZYg,11546
-librus_python_api-1.0.3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-librus_python_api-1.0.3.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
-librus_python_api-1.0.3.dist-info/RECORD,,
+librus_python_api/transport.py,sha256=QnYXnrv1lW4qToYoTv6HyZw-Lt4rDc-_SMTJpMp6_bc,35297
+librus_python_api-1.2.1.dist-info/METADATA,sha256=2EBX-fUeSn5fa9MG7Bgda1npQo-xnBbcgzhuFvnilJ0,11546
+librus_python_api-1.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+librus_python_api-1.2.1.dist-info/licenses/LICENSE,sha256=IuerLb3cnZCsaB23znydjjvKqP-LmSJd3syKa9NGUts,1071
+librus_python_api-1.2.1.dist-info/RECORD,,