librus-python-api 1.0.2__tar.gz → 1.2.1__tar.gz

{librus_python_api-1.0.2 → librus_python_api-1.2.1}/API.md

@@ -399,13 +399,45 @@ redirects, fallback, post-send lookup or implicit reauthentication. Cancel/shutd
 propagate normally with an inspectable outcome after joined cleanup, as below.
 Modern list/content reads do not reconcile durable UNKNOWN send history.
 
-- `modern_messages_page(folder=RECEIVED, *, page=1, page_size=10, budget=None,
-  max_age_seconds=0)` returns `ModernMessagesPage`. Pages are one-based. This GET
-  returns summaries only; sent read status can be unknown.
+- `modern_messages_page(folder=RECEIVED, *, page=1, page_size=10, archived=False,
+  budget=None, max_age_seconds=0)` returns `ModernMessagesPage`. Pages are
+  one-based. This GET returns summaries only; sent read status can be unknown.
 - `modern_messages(folder=RECEIVED, *, cursor=None, page_size=50, max_pages=4,
-  limit=128, budget=None, max_age_seconds=0)` returns `ModernMessages` with explicit
-  truncation, duplicate counts and account/folder/page-size-bound continuation.
+  limit=128, archived=False, budget=None, max_age_seconds=0)` returns
+  `ModernMessages` with explicit truncation, duplicate counts and
+  account/folder/mailbox/page-size-bound continuation.
   Cursor drift and later-page errors never return partial output.
+- `archived=True` (1.1.0) lists the archive mailbox instead of the current one.
+  Pages, collections, cursors and references carry `archived`; a cursor never
+  continues the other mailbox. Archived content opens raise
+  `UNSUPPORTED_CAPABILITY` because no archived content route or mark-read effect
+  is established. Archive pages and collections report the upstream
+  `archivingInProgress` status as `archiving_in_progress` (`None` for the
+  current mailbox). Live archives report `true` while listing normally, so it
+  is informational; before 1.2.1 it wrongly made every archive read
+  `UNSUPPORTED_CAPABILITY`.
+- `modern_correspondents(folder=RECEIVED, *, budget=None, max_age_seconds=0)`
+  (1.2.0) returns `ModernCorrespondents`: the senders (received) or receivers
+  (sent) the web app offers in its filter panel. Each `ModernCorrespondent` has
+  `first_name`, `last_name` (one may be empty, never both) and a login-bound
+  `ModernCorrespondentReference`.
+- `modern_messages_page()` and `modern_messages()` accept `correspondent=` (a
+  reference for the same folder and login) and, for the received folder,
+  `unread_only=True` (1.2.0). They send the web app's own `senderId`,
+  `receiverId` and `unreadOnly` filters. Results and cursors record the filter,
+  and a cursor never continues a differently filtered list. Filters on the
+  archive mailbox raise `UNSUPPORTED_CAPABILITY`; they were not observed there.
+- `modern_teacher_subjects(*, budget=None, max_age_seconds=0)` (1.2.0) returns
+  `ModernTeacherSubjects`: `ModernTeacherSubject(teacher_identifier, subject)`
+  pairs, one per subject a teacher teaches the student. Identical repeated rows
+  collapse to one (1.2.1). The identifier is the
+  teacher's modern account ID; it is informational and not a recipient reference.
+- `modern_unread_counts(*, budget=None, max_age_seconds=0)` (1.1.0) returns
+  `ModernUnreadCounts` with `current` and `archive` `ModernUnreadFolders`:
+  `inbox`, `notes`, `alerts`, `substitutions`, `absences`, `justifications` and
+  `trash`. It opens no message. A missing or invalid counter fails with `PARSE`;
+  unknown extra counters are ignored. Populated counter semantics beyond the
+  observed field names are not independently established.
   Page size is 1-50, page number 1-1,000, `max_pages` 1-8, `limit` 1-256 and
   cursor history at most 2,000 IDs. These are library bounds, not upstream maxima.
 - `modern_message_content(reference, *, allow_mark_read=False, budget=None,

{librus_python_api-1.0.2 → librus_python_api-1.2.1}/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 1.2.1 (2026-10-06) - Live fixes for archive listing and teacher subjects
+
+Compatible patch release found by the new pre-publication live check. 1.1.0 and
+1.2.0 were tagged but not published to PyPI because that check failed.
+
+- List the modern archive mailbox. Live archive pages report
+  `archivingInProgress: true` while listing normally, and 1.1.0/1.2.0 treated
+  that as unsupported, so every archive read failed. Archive pages and
+  collections now report it as `archiving_in_progress`; the current mailbox
+  still refuses the flag.
+- Collapse identical repeated rows in `modern_teacher_subjects()` instead of
+  failing with `PARSE`.
+
+## 1.2.0 (2026-10-06) - Modern correspondent filters and teacher subjects
+
+Compatible minor release. Existing calls and results are unchanged; new fields
+have defaults.
+
+- Add `modern_correspondents(folder)`, listing the senders (received) or
+  receivers (sent) the modern mailbox can be filtered by.
+- Filter `modern_messages_page()` and `modern_messages()` by `correspondent=`
+  and, for received messages, `unread_only=True`, using the web app's own
+  query filters. Pages, collections and cursors record the filter; a cursor
+  never continues a differently filtered list. The archive mailbox does not
+  accept filters.
+- Add `modern_teacher_subjects()`, pairing teachers' modern account IDs with
+  the subjects they teach the student.
+
+## 1.1.0 (2026-10-06) - Modern archive mailbox and unread counts
+
+Compatible minor release. Existing calls and results are unchanged; new fields
+have defaults.
+
+- List the modern archive mailbox (earlier school years) with
+  `modern_messages_page(..., archived=True)` and `modern_messages(...,
+  archived=True)`. Pages, collections, cursors and message references gain an
+  `archived` field (default `False`), and a cursor never continues the other
+  mailbox. Opening an archived message raises `UNSUPPORTED_CAPABILITY` until an
+  archived content route is established.
+- Add `modern_unread_counts()`, returning `ModernUnreadCounts` with current and
+  archive `ModernUnreadFolders` counters (inbox, notes, alerts, substitutions,
+  absences, justifications, trash) from the modern mailbox's own counter route.
+  It opens no message.
+
+## 1.0.3 (2026-10-06) - Notification counts for parent logins
+
+Compatible patch release. The public library API is unchanged.
+
+- Read `notification_counts()` from the information page (`/informacja`), which
+  every login can open, instead of the student landing route `/uczen/index`.
+  That route returned 403 for a parent login in a live check, and the session
+  was unusable afterwards. The counters come from the menu shared by every
+  page, so the result is unchanged for student logins. The read is now
+  retry-safe: a proven session expiry is recovered once.
+- Count the modern messages launcher link (`/wiadomosci3`) as the messages
+  category. Before, schools linking it showed no messages counter.
+- Keep `/uczen/index` only as an accepted login redirect target. It is never
+  requested directly.
+
 ## 1.0.2 (2026-10-06) - Faster shared request policy
 
 Compatible patch release. The public library API is unchanged.

{librus_python_api-1.0.2 → librus_python_api-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.0.2
+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.2
+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.2-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.2 → librus_python_api-1.2.1}/README.md

@@ -25,7 +25,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.2
+python -m pip install librus-python-api==1.2.1
 ```
 
 Pin the exact version qualified by your application. Before publication, use a
@@ -41,7 +41,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.2-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.2 → librus_python_api-1.2.1}/src/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.2"
+__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-1.0.2 → librus_python_api-1.2.1}/src/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",
@@ -337,8 +391,10 @@ ENDPOINTS: Mapping[str, Endpoint] = MappingProxyType(
                 False,
                 Evidence.SYNTHETIC_ONLY,
             ),
+            # Accepted only as a redirect target during login. Never requested
+            # directly: it answers parent logins with 403.
             Endpoint(
-                "notification_counts",
+                "login_student_landing",
                 "GET",
                 "/uczen/index",
                 SideEffect.AUTHENTICATION,
@@ -695,6 +751,10 @@ CHECKPOINT_TIMEOUT_SECONDS = 5.0
 CHECKPOINT_MAX_TIMEOUT_SECONDS = 30.0
 SCHEDULE_RESPONSE_VERSION = 1
 SCHEDULE_MAX_EVENTS = 1024
+# Every Synergia page carries the counter menu. The information page is
+# readable by student and parent logins alike; the student landing route
+# (/uczen/index) answers parent logins with 403 and is not used.
+NOTIFICATION_COUNTS_ENDPOINT = "student_information"
 NOTIFICATION_MAX_MENU_ITEMS = 64
 NOTIFICATION_MAX_COUNT = 1000000
 NOTIFICATION_DESTINATIONS = MappingProxyType(
@@ -702,6 +762,7 @@ NOTIFICATION_DESTINATIONS = MappingProxyType(
         "/przegladaj_oceny/uczen": "grades",
         "/przegladaj_nb/uczen": "attendance",
         "/wiadomosci": "messages",
+        "/wiadomosci3": "messages",
         "/ogloszenia": "announcements",
         "/terminarz": "agenda",
         "/moje_zadania": "homework",
@@ -871,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:
@@ -890,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-1.0.2 → librus_python_api-1.2.1}/src/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)