python-casahome 0.2.0__py3-none-any.whl

casahome/models/visits.py

@@ -0,0 +1,158 @@
+"""Provisional visit and conversation reads, with no call grants or controls.
+
+Fields inferred from the app. Envelopes haven't been observed live.
+Task-item and conversation-part unions stay opaque JSON, not guessed tags.
+The older requests.VendorVisit stays unchanged for compatibility.
+"""
+
+from pydantic import JsonValue
+
+from casahome.models._base import CasaModel
+from casahome.models.images import MediaAttachment
+from casahome.models.purchases import RequestPurchase
+from casahome.models.requests import VendorVisitCalendarEvent
+
+
+class MemberInvoicePreview(CasaModel):
+    id: str
+    vendor_name: str
+    amount_display: str
+    user_collection_status: str
+    status: str
+
+
+class VendorVisitMessagePreview(CasaModel):
+    sender_name: str
+    sent_at: int
+    message: str
+
+
+class VendorVisitRequestSummary(CasaModel):
+    id: str
+    type: str
+    status: str
+    title: str
+    emoji: str
+    has_unread_messages: bool
+    message_preview: VendorVisitMessagePreview | None = None
+
+
+class VisitDetailVendor(CasaModel):
+    id: str
+    display_name: str
+    compact_display_name: str
+    type: str
+    image_url: str | None = None
+    image_cache_key: str | None = None
+    active_work_started_at: int | None = None
+
+
+class VisitConversationWindow(CasaModel):
+    state: str
+    opens_at: int | None = None
+    closes_at: int | None = None
+    closed_reason: str | None = None
+
+
+class VisitConversationLiveCall(CasaModel):
+    call_id: str
+    started_at: int
+    caption: str
+
+
+class VisitConversationCounterparty(CasaModel):
+    user_id: str
+    role: str
+    vendor_id: str | None = None
+    display_name: str
+    avatar_url: str | None = None
+    avatar_url_cache_key: str | None = None
+
+
+class VisitConversationParticipant(VisitConversationCounterparty):
+    is_me: bool
+
+
+class VisitConversationLatestMessage(CasaModel):
+    sender_display_name: str
+    sent_at: int
+    message: str
+
+
+class VisitConversationSummary(CasaModel):
+    thread_id: str | None = None
+    window: VisitConversationWindow
+    counterparties: list[VisitConversationCounterparty]
+    live_call: VisitConversationLiveCall | None = None
+    calls_enabled: bool | None = None
+    unread_count: int
+    latest_message: VisitConversationLatestMessage | None = None
+
+
+class VisitConversationMessage(CasaModel):
+    id: str
+    thread_id: str
+    created_at: int
+    sender_role: str
+    sender_user_id: str
+    sender_display_name: str
+    sender_avatar_url: str | None = None
+    sender_avatar_url_cache_key: str | None = None
+    is_mine: bool
+    content: str | None = None
+    attachments: list[MediaAttachment]
+    parts: list[JsonValue]
+
+
+class VisitConversation(CasaModel):
+    visit_id: str
+    thread_id: str | None = None
+    window: VisitConversationWindow
+    calls_enabled: bool | None = None
+    live_call: VisitConversationLiveCall | None = None
+    unread_count: int
+    participants: list[VisitConversationParticipant]
+    messages: list[VisitConversationMessage]
+    event_cursor: str | None = None
+
+
+class VisitCallParticipant(CasaModel):
+    user_id: str
+    role: str
+    rang_at: int | None = None
+    joined_at: int | None = None
+    left_at: int | None = None
+
+
+class VisitCall(CasaModel):
+    id: str
+    vendor_visit_id: str
+    status: str
+    started_by_user_id: str
+    started_by_role: str
+    started_at: int
+    answered_at: int | None = None
+    ended_at: int | None = None
+    duration_seconds: int | None = None
+    recorded: bool
+    participants: list[VisitCallParticipant]
+
+
+class VisitCallsResponse(CasaModel):
+    calls: list[VisitCall]
+
+
+class VendorVisitDetails(CasaModel):
+    id: str
+    type: str
+    status: str
+    request: VendorVisitRequestSummary
+    calendar_event: VendorVisitCalendarEvent | None = None
+    vendors: list[VisitDetailVendor]
+    task_items: list[JsonValue]
+    invoices: list[MemberInvoicePreview]
+    purchases: list[RequestPurchase]
+    can_add_remove_items: bool
+    can_cancel: bool
+    feedback: JsonValue = None
+    conversation: VisitConversationSummary | None = None

casahome/models/write_contracts.py

@@ -0,0 +1,147 @@
+"""Static-only write codecs. Backend acceptance and business semantics are UNVERIFIED.
+
+Request encoders, coding keys and response shapes were inferred from the Casa
+iOS app. The reconstructed wire contracts are LIKELY, not confirmed live.
+These models neither authorize nor execute operations.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictStr, ValidationError
+
+from casahome.exceptions import CasaRequestError
+from casahome.models._base import CasaModel
+from casahome.models.requests import RequestMessage
+from casahome.models.todos import AttachMediaPayload as LegacyAttachMediaPayload
+from casahome.models.todos import CreateTodoBody as LegacyCreateTodoBody
+from casahome.models.todos import TodoDetail
+
+WRITE_TEXT_MAX_CHARS = 10_000
+"""Cap on free-text write fields (to-do content, message content, property values).
+
+Not a server limit, which is UNKNOWN. It bounds what a caller, or an agent
+driving one, can send in a single write. Real to-dos and messages are short.
+"""
+
+_WriteText = Annotated[str, Field(max_length=WRITE_TEXT_MAX_CHARS)]
+
+_WRITE_CONFIG = ConfigDict(
+    extra="forbid", strict=True, validate_assignment=True, revalidate_instances="always"
+)
+
+
+class _WriteModel(BaseModel):
+    """Reject coercion and unknown write fields, including nested fields."""
+
+    model_config = _WRITE_CONFIG
+
+
+class AttachMediaPayload(LegacyAttachMediaPayload):
+    """Existing upload IDs only. No upload, URL fetch or lifecycle inference.
+
+    The recovered codec always encodes upload_ids, including an empty list.
+    This strict public companion requires callers to supply that list explicitly.
+    """
+
+    model_config = _WRITE_CONFIG
+    upload_ids: list[str] = Field(...)
+
+
+class CreateTodoBody(LegacyCreateTodoBody):
+    """Strict public companion to the legacy todo body, with the same wire keys."""
+
+    model_config = _WRITE_CONFIG
+    content: _WriteText
+    attachments: AttachMediaPayload | None = None
+
+
+class CreateTodoResponse(CasaModel):
+    """Required app envelope. A missing flag must never become false.
+
+    TodoDetail is the existing model. Its nested opaque fields aren't re-audited.
+    A true flag isn't permission to perform any support confirmation.
+    """
+
+    todo: TodoDetail
+    needs_support_confirmation: StrictBool
+
+
+class SendRequestMessageRequest(_WriteModel):
+    """Optional fields use omission, not null. Only member role is public input.
+
+    The app codec also represents privileged roles. Their authorization is
+    UNVERIFIED, so they aren't accepted here. No content requirement is inferred.
+    """
+
+    content: _WriteText | None = None
+    attachments: AttachMediaPayload | None = None
+    sender_role: Literal["member"] | None = None
+
+
+class SendRequestMessageResponse(CasaModel):
+    """Required message envelope, reusing RequestMessage without new media variants."""
+
+    message: RequestMessage
+
+
+class UpdateMultiEnumProperty(_WriteModel):
+    """Both selection states are encoded. Server deselection semantics are unknown."""
+
+    id: str
+    is_selected: StrictBool
+
+
+class UpdateEntityProperty(_WriteModel):
+    """String-valued write property, not an arbitrary read-model scalar.
+
+    The codec doesn't enforce mutual exclusion among the optional value fields.
+    Server acceptance of combinations, duplicates and empty values is UNVERIFIED.
+    """
+
+    definition_id: str
+    value: _WriteText | None = None
+    enum_id: str | None = None
+    multi_enums: list[UpdateMultiEnumProperty] | None = None
+
+
+class UpdateEntityPropertiesRequest(_WriteModel):
+    """Required props list with optional make/model strings. No null clear operation."""
+
+    make_id: str | None = None
+    model_id: str | None = None
+    props: list[UpdateEntityProperty]
+
+
+class BasicMessageResponse(CasaModel):
+    """Required status string. The PATCH doesn't return an updated entity."""
+
+    message: StrictStr
+
+
+def _write_payload(body: BaseModel, schema: type[BaseModel]) -> dict[str, Any]:
+    """Revalidate at the I/O boundary, including copied or mutated nested models.
+
+    Accept valid legacy todo bodies without accepting their permissive extras.
+    Validate strict instances directly so model_copy's unknown fields can't hide
+    behind serialization. Python-mode dumping adapts valid legacy bodies without
+    coercing their values. Only the validated result is JSON-encoded, recursively
+    omitting None but preserving empty values.
+    """
+    if not isinstance(body, BaseModel):
+        raise TypeError("write body must be a Pydantic request model")
+    source = (
+        body
+        if isinstance(body, schema)
+        else body.model_dump(mode="python", round_trip=True, warnings=False)
+    )
+    try:
+        validated = schema.model_validate(source)
+    except ValidationError as err:
+        message = f"Invalid {schema.__name__} write body: {err.error_count()} validation error(s)"
+    else:
+        return validated.model_dump(mode="json", exclude_none=True)
+    # Raise outside the handler, like _parse. Pydantic's error echoes input
+    # values, and an implicit __context__ would leak them in tracebacks.
+    raise CasaRequestError(message)

casahome/streaming.py

@@ -0,0 +1,278 @@
+"""Opt-in CasaAI SSE support. Payload and replay behavior remain UNVERIFIED.
+
+The app uses GET, after plus Last-Event-ID, thread.update JSON, and a
+terminal resync_required event. Change discriminator values aren't known.
+Nothing in an event is executed, fetched, or treated as an instruction.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Iterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Literal, TypeVar, cast
+
+import aiohttp
+from pydantic import JsonValue
+
+from .client import CasaClient
+from .const import CASA_APP, CASA_APP_VERSION, USER_AGENT
+from .exceptions import CasaApiError, CasaAuthError, CasaConnectionError, CasaResponseError
+
+MAX_EVENT_BYTES = 256 * 1024
+MAX_LINE_BYTES = 64 * 1024
+MAX_CURSOR_LENGTH = 2048
+STREAM_READ_TIMEOUT = 60.0
+_CHUNK_BYTES = 16 * 1024
+
+
+@dataclass(frozen=True)
+class ServerSentEvent:
+    """SSE fields. An absent or empty event field becomes the standard message type.
+
+    id persists across dispatches. data is joined text, including unknown events.
+    These values can contain member content. Don't log them indiscriminately.
+    """
+
+    event: str
+    id: str | None
+    data: str
+
+
+@dataclass(frozen=True)
+class CasaAIThreadUpdateEvent(ServerSentEvent):
+    """thread.update with JSON preserved without guessing nested wire variants."""
+
+    event: Literal["thread.update"]
+    payload: JsonValue
+
+
+@dataclass(frozen=True)
+class CasaAIResyncRequiredEvent(ServerSentEvent):
+    """Terminal resync signal. The caller decides how to reload and resume."""
+
+    event: Literal["resync_required"]
+
+
+CasaAIEvent = CasaAIThreadUpdateEvent | CasaAIResyncRequiredEvent | ServerSentEvent
+_F = TypeVar("_F", bound=Callable[..., AsyncIterator[CasaAIEvent]])
+
+
+def unverified_stream(func: _F) -> _F:
+    """Mark an async generator without changing its identity or coroutine markers."""
+    func.__casa_unverified__ = True  # type: ignore[attr-defined]
+    func.__doc__ = (
+        "UNVERIFIED: payload decoding and replay behavior aren't established against live data. "
+        "Live traffic (2026-10) confirmed GET/SSE transport only.\n\n" + (func.__doc__ or "")
+    ).rstrip()
+    return func
+
+
+def _validate_cursor(after: str | None) -> None:
+    """Keep cursors opaque, but safe for the matching query and HTTP header."""
+    if after is not None and (
+        not isinstance(after, str)
+        or len(after) > MAX_CURSOR_LENGTH
+        or any(ord(c) < 32 or 127 <= ord(c) <= 159 for c in after)
+        or any(0xD800 <= ord(c) <= 0xDFFF for c in after)
+    ):
+        raise ValueError("after must be a cursor of at most 2048 characters without controls")
+
+
+class SSEParser:
+    """Incremental bounded UTF-8 SSE parser. EOF discards an unfinished event.
+
+    Supports LF, CRLF, and CR, comments, multiline data, a leading BOM, persistent
+    IDs, and the standard empty ID reset. NUL IDs are ignored. Unknown fields,
+    including retry, are ignored. Bounds include comments and unknown fields in
+    each blank-line-delimited block. CRLF counts as one line-ending byte.
+    feed is lazy, so stopping at a terminal event doesn't parse later bytes.
+    """
+
+    def __init__(
+        self,
+        *,
+        last_event_id: str | None = None,
+        max_event_bytes: int = MAX_EVENT_BYTES,
+        max_line_bytes: int = MAX_LINE_BYTES,
+    ) -> None:
+        for value in (max_event_bytes, max_line_bytes):
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ValueError("SSE byte limits must be positive integers")
+        self._max_event_bytes = max_event_bytes
+        self._max_line_bytes = max_line_bytes
+        self._line = bytearray()
+        self._block_bytes = 0
+        self._skip_lf = False
+        self._first_line = True
+        self._event = ""
+        self._id = last_event_id
+        self._data: list[str] = []
+
+    def feed(self, chunk: bytes) -> Iterator[ServerSentEvent]:
+        """Consume a bounded chunk and yield only blank-line-terminated events."""
+        for byte in chunk:
+            if self._skip_lf:
+                self._skip_lf = False
+                if byte == 10:
+                    continue
+            self._block_bytes += 1
+            if self._block_bytes > self._max_event_bytes:
+                raise CasaResponseError("SSE event exceeds byte limit")
+            if byte in (10, 13):
+                self._skip_lf = byte == 13
+                event = self._consume_line()
+                self._line.clear()
+                if event is not None:
+                    yield event
+            else:
+                if len(self._line) >= self._max_line_bytes:
+                    raise CasaResponseError("SSE line exceeds byte limit")
+                self._line.append(byte)
+
+    def _consume_line(self) -> ServerSentEvent | None:
+        line = self._line.decode("utf-8", errors="replace")
+        if self._first_line:
+            line = line.removeprefix("\ufeff")
+            self._first_line = False
+        if not line:
+            event = (
+                ServerSentEvent(self._event or "message", self._id, "\n".join(self._data))
+                if self._data
+                else None
+            )
+            self._event = ""
+            self._data.clear()
+            self._block_bytes = 0
+            return event
+        if line.startswith(":"):
+            return None
+        field, separator, value = line.partition(":")
+        if separator:
+            value = value.removeprefix(" ")
+        if field == "event":
+            self._event = value
+        elif field == "id" and "\x00" not in value:
+            self._id = value
+        elif field == "data":
+            self._data.append(value)
+        return None
+
+
+def _reject_constant(value: str) -> None:
+    raise ValueError("Non-JSON numeric constant")
+
+
+def _finite_float(value: str) -> float:
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError("Nonfinite JSON number")
+    return number
+
+
+def _typed_event(event: ServerSentEvent) -> CasaAIEvent:
+    if event.event == "resync_required":
+        return CasaAIResyncRequiredEvent("resync_required", event.id, event.data)
+    if event.event == "thread.update":
+        # Don't retain a decoding exception as cause/context. It can hold raw data.
+        try:
+            payload = cast(
+                JsonValue,
+                json.loads(event.data, parse_constant=_reject_constant, parse_float=_finite_float),
+            )
+            valid = True
+        except (ValueError, RecursionError):
+            payload = None
+            valid = False
+        if not valid:
+            raise CasaResponseError("Malformed thread.update JSON")
+        return CasaAIThreadUpdateEvent("thread.update", event.id, event.data, payload)
+    return event
+
+
+@asynccontextmanager
+async def _safe_stream_errors() -> AsyncIterator[None]:
+    """Keep transport errors free of URLs, tokens, and remote body snippets."""
+    error: CasaConnectionError | CasaAuthError | None = None
+    try:
+        yield
+    except TimeoutError:
+        error = CasaConnectionError("SSE request timed out")
+    except (aiohttp.ClientError, CasaConnectionError):
+        error = CasaConnectionError("SSE connection failed")
+    except CasaAuthError:
+        error = CasaAuthError("SSE authentication failed")
+    if error is not None:
+        # athrow() resumes this context manager under the caller's exception.
+        # Clear that implicit context too, not only the displayed traceback.
+        try:
+            raise error from None
+        finally:
+            error.__context__ = None
+
+
+async def _stream_events(
+    client: CasaClient, path: str, after: str | None
+) -> AsyncGenerator[CasaAIEvent, None]:
+    """Internal fixed-route transport. The API validates the path and cursor.
+
+    CasaClient has no public session/base/timeout accessors. Read those existing
+    fields here only, without changing ownership or bypassing FirebaseAuth's
+    cache and token-specific invalidation. JSON request() can't stream and its
+    error-body helper exposes raw snippets, so neither is used for SSE bodies.
+    """
+    timeout = aiohttp.ClientTimeout(
+        total=None,
+        connect=min(client._timeout.total or STREAM_READ_TIMEOUT, STREAM_READ_TIMEOUT),
+        sock_read=STREAM_READ_TIMEOUT,
+    )
+    async with _safe_stream_errors():
+        for attempt in range(2):
+            token = await client.auth.get_id_token()
+            headers = {
+                "Authorization": f"Bearer {token}",
+                "X-Casa-App": CASA_APP,
+                "X-Casa-App-Version": CASA_APP_VERSION,
+                "User-Agent": USER_AGENT,
+                "Accept": "text/event-stream",
+            }
+            params = None
+            if after is not None:
+                headers["Last-Event-ID"] = after
+                params = {"after": after}
+            async with client._session.get(
+                client._base_url + path,
+                headers=headers,
+                params=params,
+                timeout=timeout,
+                allow_redirects=False,
+                raise_for_status=False,
+            ) as response:
+                try:
+                    if response.status == 401:
+                        response.close()
+                        if attempt:
+                            raise CasaAuthError("Casa rejected the refreshed token (HTTP 401)")
+                        client.auth.invalidate(token)
+                        continue
+                    if response.status == 204:
+                        return
+                    if response.status != 200:
+                        # No error-body read, even for JSON. Status is safe metadata.
+                        raise CasaApiError(response.status, "stream_http_error")
+                    if response.content_type != "text/event-stream":
+                        raise CasaResponseError("Expected text/event-stream response")
+                    parser = SSEParser(last_event_id=after)
+                    while chunk := await response.content.read(_CHUNK_BYTES):
+                        for raw in parser.feed(chunk):
+                            event = _typed_event(raw)
+                            if isinstance(event, CasaAIResyncRequiredEvent):
+                                response.close()
+                                yield event
+                                return
+                            yield event
+                    return
+                finally:
+                    response.close()