librus-python-api 1.0.0__py3-none-any.whl

librus_python_api/modern_messages.py

@@ -0,0 +1,276 @@
+"""Original bounded modern directory parsers; no scripts or backend fallback."""
+
+import json
+import re
+from typing import Any
+
+from librus_python_api.config import (
+    MODERN_DIRECTORY_TYPE_PATTERN,
+    MODERN_MAX_CLASSES,
+    MODERN_MAX_LABEL,
+    MODERN_MAX_RECIPIENTS,
+    MODERN_MAX_TOTAL_TEXT,
+    MODERN_MAX_TYPES,
+    MODERN_RECIPIENT_OPERATIONS,
+    MODERN_REJECTION_CODES,
+    MODERN_SUPPORTED_ACCOUNT_GROUPS,
+    modern_directory_query,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import (
+    ModernAccountData,
+    ModernRecipient,
+    ModernRecipientReference,
+    ModernRecipientType,
+    ModernRecipientTypeReference,
+    SendStatus,
+)
+from librus_python_api.parsers import decode_json
+
+
+def _object(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LibrusError(ErrorKind.PARSE)
+    return value
+
+
+def _label(value: Any) -> str:
+    if (
+        type(value) is not str
+        or not value.strip()
+        or len(value) > MODERN_MAX_LABEL
+        or any(ord(c) < 32 for c in value)
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    return value
+
+
+def _identifier(value: Any) -> str:
+    if type(value) is not str or re.fullmatch(r"[0-9]{1,64}", value) is None:
+        raise LibrusError(ErrorKind.PARSE)
+    return value
+
+
+def parse_modern_identity(body: bytes) -> ModernAccountData:
+    data = _object(decode_json(body))
+    raw_identifier = data.get("accountId")
+    # Identity alone independently returned a JSON integer. Keep recipient IDs
+    # strict and reject bool/float/negative/oversized values before normalization.
+    if type(raw_identifier) is int and 0 <= raw_identifier < 10**64:
+        raw_identifier = str(raw_identifier)
+    identifier = _identifier(raw_identifier)
+    if (
+        data.get("originSystem") != "synergia"
+        or type(data.get("groupId")) is not str
+        or data.get("groupId") not in MODERN_SUPPORTED_ACCOUNT_GROUPS
+    ):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    return ModernAccountData(
+        identifier,
+        data["groupId"],
+        _label(data.get("firstName")),
+        _label(data.get("lastName")),
+    )
+
+
+def parse_modern_types(body: bytes, account: str) -> tuple[ModernRecipientType, ...]:
+    data = _object(_object(decode_json(body)).get("data"))
+    entries = data.get("list")
+    if not isinstance(entries, list) or len(entries) > MODERN_MAX_TYPES:
+        raise LibrusError(ErrorKind.PARSE)
+    result = []
+    seen = set()
+    for item in entries:
+        value = _object(item)
+        identifier = value.get("id")
+        if (
+            type(identifier) is not str
+            or (
+                identifier not in MODERN_RECIPIENT_OPERATIONS
+                and MODERN_DIRECTORY_TYPE_PATTERN.fullmatch(identifier) is None
+            )
+            or identifier in seen
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        seen.add(identifier)
+        result.append(
+            ModernRecipientType(
+                ModernRecipientTypeReference(identifier, account),
+                _label(value.get("name")),
+                identifier in MODERN_RECIPIENT_OPERATIONS,
+            )
+        )
+    if "defaultGroup" in data and (
+        type(data["defaultGroup"]) is not str or data["defaultGroup"] not in seen
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    return tuple(result)
+
+
+def validate_modern_type(reference: ModernRecipientTypeReference, account: str) -> None:
+    if (
+        not isinstance(reference, ModernRecipientTypeReference)
+        or reference.account != account
+    ):
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    modern_directory_query(
+        reference.identifier, include_virtual=reference.include_virtual
+    )
+
+
+def parse_modern_recipients(
+    body: bytes, reference: ModernRecipientTypeReference
+) -> tuple[ModernRecipient, ...]:
+    validate_modern_type(reference, reference.account)
+    data = _object(decode_json(body))
+    if MODERN_RECIPIENT_OPERATIONS[reference.identifier] != "modern_recipients":
+        return _employee_recipients(data, reference)
+    field = "classes" if "classes" in data else "data"
+    classes = data.get(field)
+    if (
+        set(data) != {field}
+        or not isinstance(classes, list)
+        or len(classes) > MODERN_MAX_CLASSES
+    ):
+        raise LibrusError(ErrorKind.PARSE)
+    result: list[ModernRecipient] = []
+    labels: set[str] = set()
+    seen: set[str] = set()
+    total = 0
+    for raw_class in classes:
+        klass = _object(raw_class)
+        label = _label(klass.get("label"))
+        groups = klass.get("receivers")
+        if (
+            set(klass) != {"label", "receivers"}
+            or label in labels
+            or not isinstance(groups, list)
+            or len(groups) != 1
+            or not isinstance(groups[0], list)
+        ):
+            raise LibrusError(ErrorKind.PARSE)
+        labels.add(label)
+        total += len(label)
+        if total > MODERN_MAX_TOTAL_TEXT:
+            raise LibrusError(ErrorKind.LIMIT)
+        if len(result) + len(groups[0]) > MODERN_MAX_RECIPIENTS:
+            raise LibrusError(ErrorKind.LIMIT)
+        for raw in groups[0]:
+            leaf = _object(raw)
+            if set(leaf) != {"accountId", "userId", "name"}:
+                raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+            identifier, user = (
+                _identifier(leaf.get("accountId")),
+                _identifier(leaf.get("userId")),
+            )
+            name = _label(leaf.get("name"))
+            if identifier in seen:
+                raise LibrusError(ErrorKind.PARSE)
+            seen.add(identifier)
+            total += len(name)
+            if total > MODERN_MAX_TOTAL_TEXT:
+                raise LibrusError(ErrorKind.LIMIT)
+            result.append(
+                ModernRecipient(
+                    ModernRecipientReference(
+                        identifier,
+                        user,
+                        reference.account,
+                        reference.identifier,
+                        label,
+                        reference.include_virtual,
+                    ),
+                    name,
+                )
+            )
+    return tuple(result)
+
+
+def _employee_recipients(
+    data: dict[str, Any], reference: ModernRecipientTypeReference
+) -> tuple[ModernRecipient, ...]:
+    entries = data.get("receivers")
+    if set(data) != {"receivers"} or not isinstance(entries, list):
+        raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+    if len(entries) > MODERN_MAX_RECIPIENTS:
+        raise LibrusError(ErrorKind.LIMIT)
+    result = []
+    seen = set()
+    total = 0
+    for raw in entries:
+        leaf = _object(raw)
+        if not {"accountId", "userId", "label"} <= set(leaf) or set(leaf) - {
+            "accountId",
+            "userId",
+            "label",
+            "availabilityStatus",
+        }:
+            raise LibrusError(ErrorKind.UNSUPPORTED_CAPABILITY)
+        identifier, user = _identifier(leaf["accountId"]), _identifier(leaf["userId"])
+        if identifier in seen:
+            raise LibrusError(ErrorKind.PARSE)
+        seen.add(identifier)
+        label = _label(leaf["label"])
+        # Availability is exposed as inert bounded JSON, not invented permission,
+        # work-hours or delivery semantics. It never changes the send payload.
+        availability = leaf.get("availabilityStatus")
+        try:
+            encoded = (
+                None
+                if availability is None
+                else json.dumps(
+                    availability,
+                    separators=(",", ":"),
+                    ensure_ascii=True,
+                    allow_nan=False,
+                )
+            )
+        except ValueError:
+            raise LibrusError(ErrorKind.PARSE) from None
+        if encoded is not None and len(encoded) > MODERN_MAX_LABEL:
+            raise LibrusError(ErrorKind.LIMIT)
+        total += len(label) + len(encoded or "")
+        if total > MODERN_MAX_TOTAL_TEXT:
+            raise LibrusError(ErrorKind.LIMIT)
+        result.append(
+            ModernRecipient(
+                ModernRecipientReference(
+                    identifier, user, reference.account, reference.identifier, ""
+                ),
+                label,
+                encoded,
+            )
+        )
+    return tuple(result)
+
+
+def parse_modern_send_response(body: bytes, status: int) -> SendStatus:
+    """Accept only the observed created/sent envelope, never HTTP success alone."""
+    data = _object(decode_json(body))
+    if status == 201 and set(data) == {"data"}:
+        receipt = data["data"]
+        if (
+            type(receipt) is dict
+            and set(receipt) == {"messageId", "status"}
+            and receipt["status"] == "sent"
+            and type(receipt["messageId"]) is int
+            and 0 < receipt["messageId"] < 10**64
+        ):
+            return SendStatus.ACCEPTED
+    if status in (400, 422) and set(data) <= {"code", "errors", "message"}:
+        codes = []
+        if "code" in data:
+            codes.append(data["code"])
+        errors = data.get("errors", [])
+        if not isinstance(errors, list) or len(errors) > 50:
+            raise LibrusError(ErrorKind.UNKNOWN_DELIVERY)
+        for error in errors:
+            entry = _object(error)
+            if set(entry) - {"code", "message", "field"}:
+                raise LibrusError(ErrorKind.UNKNOWN_DELIVERY)
+            codes.append(entry.get("code"))
+        if codes and all(
+            type(code) is str and code in MODERN_REJECTION_CODES for code in codes
+        ):
+            return SendStatus.REJECTED
+    raise LibrusError(ErrorKind.UNKNOWN_DELIVERY)

librus_python_api/notification_models.py

@@ -0,0 +1,145 @@
+"""Neutral optional notification delivery and recovery values, never MCP DTOs."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from librus_python_api.models import (
+    AccountContext,
+    Announcement,
+    AttendanceRecord,
+    DescriptiveGrade,
+    HomeworkItem,
+    Identity,
+    MessageSummary,
+    MessagingBackend,
+    ModernMessageSummary,
+    NotificationCategory,
+    NumericGrade,
+    Observation,
+    RecentScheduleEvent,
+)
+
+type NotificationValue = (
+    NumericGrade
+    | DescriptiveGrade
+    | AttendanceRecord
+    | MessageSummary
+    | ModernMessageSummary
+    | Announcement
+    | HomeworkItem
+    | RecentScheduleEvent
+)
+
+
+class NotificationProvenance(StrEnum):
+    OBSERVED = "observed"
+    IMPORTED_HISTORY = "imported_history"
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationItem:
+    category: NotificationCategory
+    identifier: str = field(repr=False)
+    value: NotificationValue = field(repr=False)
+    identity: Identity | None = field(repr=False)
+    observation: Observation | None = field(repr=False)
+    provenance: NotificationProvenance = NotificationProvenance.OBSERVED
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationBatch:
+    receipt: str = field(repr=False)
+    context: AccountContext = field(repr=False)
+    first_run: bool
+    categories: tuple[NotificationCategory, ...]
+    items: tuple[NotificationItem, ...] = field(repr=False)
+    has_more_schedule: bool
+    messages_backend: MessagingBackend = MessagingBackend.LEGACY
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationSeen:
+    category: NotificationCategory
+    identifiers: tuple[str, ...] = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationState:
+    initialized: bool
+    seen: tuple[NotificationSeen, ...] = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationArchive:
+    """Versioned neutral bytes; includes private raw envelopes and pending delivery."""
+
+    version: int
+    context: AccountContext = field(repr=False)
+    payload: bytes = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationBaselineMapping:
+    """Caller-established mapping; None means explicitly unmappable."""
+
+    category: NotificationCategory
+    source_identifier: str = field(repr=False)
+    native_identifier: str | None = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationBootstrap:
+    """Neutral offline inputs, never a consumer's files or fabricated raw pages."""
+
+    context: AccountContext = field(repr=False)
+    mappings: tuple[NotificationBaselineMapping, ...] = field(repr=False)
+    pending_events: tuple[RecentScheduleEvent, ...] = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationBootstrapResult:
+    """Unmapped inputs prevent every write; successful history has a durable receipt."""
+
+    imported: bool
+    unmapped: tuple[NotificationBaselineMapping, ...] = field(repr=False)
+    pending: NotificationBatch | None = field(repr=False)
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationPendingDelivery:
+    """Compact delivery metadata; message/event content requires pending_batch."""
+
+    receipt: str = field(repr=False)
+    categories: tuple[NotificationCategory, ...]
+    messages_backend: MessagingBackend
+    first_run: bool
+    item_count: int
+    has_more_schedule: bool
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationRawCheckpointStatus:
+    """Retained native wire receipt, not a parsed event count or retry permission."""
+
+    identifier: str = field(repr=False)
+    cursor: int
+    total: int | None
+    wire_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class NotificationRecoveryStatus:
+    """Independent facts: an ordinary delivery may coexist with raw/uncertain work."""
+
+    context: AccountContext = field(repr=False)
+    initialized: bool
+    last_acknowledged_receipt: str | None = field(repr=False)
+    pending: NotificationPendingDelivery | None
+    raw: NotificationRawCheckpointStatus | None
+    uncertain_consume: bool
+
+    @property
+    def has_pending_work(self) -> bool:
+        return (
+            self.pending is not None or self.raw is not None or self.uncertain_consume
+        )