python-casahome 0.2.0__py3-none-any.whl

casahome/models/home.py

@@ -0,0 +1,175 @@
+"""Home inventory and weather models.
+
+Inventory entity fields are live-verified against ``inventory/v3`` (2026-10).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from ._base import CasaModel, epoch_to_dt
+from .enums import WeatherConditionField
+
+
+class SimpleEntityProp(CasaModel):
+    id: str
+    definition_id: str
+    title: str
+    key: str
+    value: Any = None
+    data_type: str | None = None
+    is_required_to_publish: bool = False
+    is_readonly: bool = False
+    format: str | None = None
+    enum_details: Any | None = None  # TODO: unresolved type SimpleEntityEnumProp
+    multi_enums: list[Any] = Field(default_factory=list)
+    enum_type: str | None = None
+    symbol_name: str | None = None
+    help_center_article_id: str | None = None
+
+
+class HomeRoom(CasaModel):
+    id: str
+    name: str
+    is_removable: bool = False
+    room_type_id: str | None = None
+    image_url: str | None = None
+    image_url_cache_key: str | None = None
+    room_properties: list[SimpleEntityProp] = Field(default_factory=list)
+
+
+class HomeStory(CasaModel):
+    id: str
+    floor_number: int
+    name: str
+    window_count: int | None = None
+    rooms: list[HomeRoom] = Field(default_factory=list)
+
+
+class HomeDetails(CasaModel):
+    id: str
+    display_address: str
+    stories: list[HomeStory] = Field(default_factory=list)
+
+
+PropertyValue = str | int | float | bool | None
+"""Scalar value carried by entity and catalog model properties (live-verified)."""
+
+
+class EntityProperty(SimpleEntityProp):
+    """A typed property on an inventory entity, e.g. ``serial_number``.
+
+    Same wire shape as :class:`SimpleEntityProp`, but the value is narrowed to
+    the scalar types observed live on ``inventory/v3``.
+    """
+
+    value: PropertyValue = None
+
+
+class EntityMake(CasaModel):
+    id: str
+    name: str
+
+
+class ModelProperty(CasaModel):
+    """A catalog property on a make/model, e.g. key ``summary``."""
+
+    id: str
+    key: str
+    caption: str | None = None
+    value: PropertyValue = None
+    data_type: str | None = None
+    format: str | None = None
+    symbol_name: str | None = None
+
+
+class EntityModel(CasaModel):
+    id: str
+    name: str
+    properties: list[ModelProperty] = Field(default_factory=list)
+
+    def property_value(self, key: str) -> PropertyValue:
+        """Return the value of the first catalog property with ``key``, else None."""
+        return next((p.value for p in self.properties if p.key == key), None)
+
+
+class EntityIdentity(CasaModel):
+    """How confidently Casa has identified the make and model."""
+
+    state: str | None = None
+    unverified_make: str | None = None
+    unverified_model: str | None = None
+    candidates: list[Any] = Field(default_factory=list)
+
+
+class EntityImage(CasaModel):
+    """Image metadata. URL and cache-key fields ride along in ``model_extra``."""
+
+    id: str
+    name: str | None = None
+    role: str | None = None
+    is_hero: bool = False
+
+
+class SimpleEntity(CasaModel):
+    """An inventory item (appliance, fixture, etc.) from ``inventory/v3``."""
+
+    id: str
+    category_id: str
+    category: str
+    status: str
+    type_id: str | None = None
+    type: str | None = None
+    type_symbol_name: str | None = None
+    created_at: int | None = None
+    inventoried_by: str | None = None
+    failure_reason: str | None = None
+    failure_item_label: str | None = None
+    issues: list[Any] = Field(default_factory=list)
+    rooms: list[str] = Field(default_factory=list)
+    stories: list[str] = Field(default_factory=list)
+    images: list[EntityImage] = Field(default_factory=list)
+    manuals: list[Any] = Field(default_factory=list)
+    thumbnail_url: str | None = None
+    thumbnail_url_cache_key: str | None = None
+    catalog_make_requirement: str | None = None
+    catalog_model_requirement: str | None = None
+    catalog_model_required: bool | None = None
+    make: EntityMake | None = None
+    model: EntityModel | None = None
+    identity: EntityIdentity | None = None
+    entity_properties: list[EntityProperty] = Field(default_factory=list)
+    associated_entity_ids: list[str] | None = None
+    is_removable: bool = False
+    is_retypable: bool | None = None
+    removal_blocked_reason: str | None = None
+    paint_match: Any | None = None
+
+    @property
+    def created_at_dt(self) -> datetime | None:
+        return epoch_to_dt(self.created_at)
+
+    def property_value(self, key: str) -> PropertyValue:
+        """Return the value of the first entity property with ``key``, else None.
+
+        Example: ``entity.property_value("serial_number")``.
+        """
+        return next((p.value for p in self.entity_properties if p.key == key), None)
+
+
+class HomeDetailsResponse(CasaModel):
+    home: HomeDetails
+    entities: list[SimpleEntity] = Field(default_factory=list)
+    room_entity_map: dict[str, list[str]] = Field(default_factory=dict)
+    associated_entities: dict[str, list[str]] = Field(default_factory=dict)
+
+
+class WeatherResponse(CasaModel):
+    temperature_degrees: float
+    temperature_units: str
+    condition_type: WeatherConditionField
+    sunrise_at: int | None = None
+    sunset_at: int | None = None

casahome/models/images.py

@@ -0,0 +1,48 @@
+"""Photo metadata only. These models never fetch their URL strings."""
+
+from pydantic import RootModel
+
+from casahome.models._base import CasaModel
+
+
+class RoomImageCandidate(CasaModel):
+    id: str
+    image_url: str
+    cache_key: str
+    is_current: bool
+
+
+class RoomMemberImage(CasaModel):
+    """UNVERIFIED populated member image. Static Codable fields."""
+
+    image_url: str | None = None
+    cache_key: str | None = None
+
+
+class RoomImageOptionsResponse(CasaModel):
+    matterport_images: list[RoomImageCandidate]
+    member_image: RoomMemberImage | None = None
+
+
+class MatterportImage(CasaModel):
+    id: str
+    image_url: str
+    cache_key: str
+    is_home_hero_image: bool
+
+
+class MatterportImagesResponse(RootModel[list[MatterportImage]]):
+    """Bare list of populated image metadata."""
+
+
+class MediaAttachment(CasaModel):
+    """Observed on to-dos. created_at is static and wasn't present there."""
+
+    id: str
+    name: str
+    mimetype: str
+    size: int
+    url: str
+    cache_key: str
+    thumbnail_url: str | None = None
+    created_at: int | None = None

casahome/models/mailbox.py

@@ -0,0 +1,160 @@
+"""Mailbox and package models (UNVERIFIED endpoints).
+
+Mailbox models use ISO 8601 string timestamps. Packages use epoch seconds.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field
+
+from ._base import CasaModel
+from .enums import PackageDirectionField, PackagePickupStatusField
+
+
+class MailboxAddress(CasaModel):
+    line1: str
+    city: str
+    state: str
+    postal_code: str
+    line2: str | None = None
+
+
+class MailboxQuota(CasaModel):
+    month: str
+    used: int
+    included: int
+    overage_rate_usd_cents: int
+    resets_on: str | None = None
+
+
+class MailboxRecipient(CasaModel):
+    id: str
+    kind: str
+    always_included: bool = False
+    first_name: str | None = None
+    last_name: str | None = None
+    business_name: str | None = None
+    is_primary: bool | None = None
+
+
+class MemberMailbox(CasaModel):
+    id: str
+    status: str
+    onboarding_status: str
+    address: MailboxAddress
+    quota: MailboxQuota
+    claimed_at: str
+    recipients: list[MailboxRecipient] = Field(default_factory=list)
+    auto_archive_days: int | None = None
+
+
+class MailboxPlan(CasaModel):
+    monthly_piece_quota: int
+    overage_rate_usd_cents: int
+
+
+class MailboxOverviewResponse(CasaModel):
+    mailbox: MemberMailbox | None = None
+    plan: MailboxPlan | None = None
+
+
+class MailboxMailItem(CasaModel):
+    id: str
+    scan_status: str
+    received_at: str
+    is_returned_to_sender: bool = False
+    check_detected: bool = False
+    sender: str | None = None
+    addressed_to: str | None = None
+    summary: str | None = None
+    scan_notice_type: str | None = None
+    clear_at: str | None = None
+    forward_status: str | None = None
+    forward_tracking_number: str | None = None
+    shred_status: str | None = None
+    deposit_status: str | None = None
+    archived_at: str | None = None
+    read_at: str | None = None
+    envelope_image_url: str | None = None
+
+
+class MailboxMailItemsResponse(CasaModel):
+    mail_items: list[MailboxMailItem] = Field(default_factory=list)
+
+
+class TrackingHistoryData(CasaModel):
+    id: str
+    source: str
+    message: str
+    timestamp: int
+    status_display_name: str
+    status_detail_display_name: str
+    city: str | None = None
+    state: str | None = None
+    country: str | None = None
+    zip: str | None = None
+    timezone: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+
+
+class PackageCarrierInfo(CasaModel):
+    carrier_id: str
+    display_name: str
+    logo_url: str
+    primary_color: str
+    pickup_eligible: bool = False
+    trackable: bool = False
+    secondary_color: str | None = None
+    pickup_requirements: list[Any] | None = None
+    pickup_qr_regex: str | None = None
+    pickup_category: str | None = None
+
+
+class PackageItem(CasaModel):
+    id: str
+    carrier_id: str
+    created_at: int
+    updated_at: int
+    status: str
+    status_detail: str
+    direction: PackageDirectionField
+    archived: bool = False
+    is_pickup: bool = False
+    can_archive: bool = False
+    suggest_archive: bool = False
+    tracking_number: str | None = None
+    weight: float | None = None
+    est_delivery_date: int | None = None
+    signed_by: str | None = None
+    service: str | None = None
+    container_type: str | None = None
+    origin_city: str | None = None
+    origin_state: str | None = None
+    origin_zip: str | None = None
+    origin_country: str | None = None
+    name: str | None = None
+    tracking_history: list[TrackingHistoryData] = Field(default_factory=list)
+    pickup_amazon_location: Any | None = None
+    pickup_qr_code: str | None = None
+    pickup_image_url: str | None = None
+    pickup_image_url_cache_key: str | None = None
+    pickup_status: PackagePickupStatusField | None = None
+    purchased_item: Any | None = None
+
+
+class PackagesResponse(CasaModel):
+    next_pickup_lockdown: int
+    next_pickup_start: int
+    next_pickup_end: int
+    current_pickup_lockdown: int | None = None
+    current_pickup_start: int | None = None
+    current_pickup_end: int | None = None
+    carriers: list[PackageCarrierInfo] = Field(default_factory=list)
+    packages: list[PackageItem] = Field(default_factory=list)
+    next_pickup_item_ids: list[str] = Field(default_factory=list)
+    current_pickup_item_ids: list[str] = Field(default_factory=list)
+    package_auto_archive_days: int | None = None
+    package_tracking_inbound_email: str | None = None

casahome/models/maintenance.py

@@ -0,0 +1,200 @@
+"""Autopilot and inventory service history.
+
+Autopilot's populated variants were observed in the saved follow-up response.
+Service history lists were empty. Their item fields come from static Codable data.
+String discriminators stay open to future server values.
+"""
+
+from pydantic import RootModel
+
+from casahome.models._base import CasaModel
+from casahome.models.requests import Pagination, RequestCard
+
+
+class AutopilotRequirementOption(CasaModel):
+    type_id: str
+    name: str
+    symbol_name: str | None = None
+    help_center_article_id: str | None = None
+
+
+class AutopilotRequirementProperty(CasaModel):
+    definition_id: str
+    entity_type_id: str
+    title: str
+
+
+class AutopilotRequirementRoomProperty(CasaModel):
+    definition_id: str
+    title: str
+    data_type: str
+    symbol_name: str | None = None
+
+
+class AutopilotRequirementRoomCandidate(CasaModel):
+    room_id: str
+    name: str
+    story_name: str
+    story_floor_number: int
+    duration_minutes: int
+    image_url: str | None = None
+    image_url_cache_key: str | None = None
+    price_usd_cents: int | None = None
+    property_value: bool | None = None
+
+
+class AutopilotPlanRequirement(CasaModel):
+    kind: str
+    options: list[AutopilotRequirementOption]
+    noun_with_article: str | None = None
+    property: AutopilotRequirementProperty | None = None
+    room_property: AutopilotRequirementRoomProperty | None = None
+    room_candidates: list[AutopilotRequirementRoomCandidate] | None = None
+
+
+class AutopilotIllustration(CasaModel):
+    bg_color: str
+    url: str | None = None
+    url_cache_key: str | None = None
+
+
+class AutopilotPricingPolicy(CasaModel):
+    symbol_name: str
+    title: str
+    description: str
+
+
+class AutopilotHomeAssociation(CasaModel):
+    id: str
+    duration_minutes: int
+    enabled: bool | None = None
+    price_usd_cents: int | None = None
+
+
+class AutopilotRoomAssociation(CasaModel):
+    id: str
+    room_id: str
+    room_name: str
+    room_story_name: str
+    duration_minutes: int
+    enabled: bool | None = None
+    room_image_url: str | None = None
+    room_image_cache_key: str | None = None
+    price_usd_cents: int | None = None
+
+
+class AutopilotEntityAssociation(CasaModel):
+    id: str
+    entity_id: str
+    entity_make: str
+    entity_model: str
+    duration_minutes: int
+    enabled: bool | None = None
+    entity_display_name: str | None = None
+    entity_location: str | None = None
+    entity_image_url: str | None = None
+    entity_image_cache_key: str | None = None
+    price_usd_cents: int | None = None
+
+
+class AutopilotPlan(CasaModel):
+    plan_id: str
+    plan_template_id: str
+    title: str
+    subtitle: str
+    description: str
+    applies_to: str
+    type: str
+    enabled: bool
+    illustration: AutopilotIllustration
+    asap_schedule_description: str
+    pricing_policies: list[AutopilotPricingPolicy]
+    fulfillment_policy: str
+    savings_percentage: int
+    cadence_options: list[str]
+    default_cadence: str
+    next_projected_occurrence_range_start: str
+    next_projected_occurrence_range_end: str
+    room_associations: list[AutopilotRoomAssociation]
+    entity_associations: list[AutopilotEntityAssociation]
+    requirement: AutopilotPlanRequirement | None = None
+    handyman_credit_policy: str | None = None
+    selected_cadence: str | None = None
+    next_desired_occurrence_date: str | None = None
+    next_calendar_event_start_at: int | None = None
+    home_association: AutopilotHomeAssociation | None = None
+
+
+class AutopilotIneligiblePlan(CasaModel):
+    plan_template_id: str
+    title: str
+    subtitle: str
+    description: str
+    type: str
+    fulfillment_policy: str
+    illustration: AutopilotIllustration
+    requirement: AutopilotPlanRequirement
+
+
+class AutopilotCategory(CasaModel):
+    category_id: str
+    category_title: str
+    category_description: str
+    category_rendering_type: str
+    plans: list[AutopilotPlan]
+    ineligible_plans: list[AutopilotIneligiblePlan]
+
+
+class AutopilotCategoriesResponse(RootModel[list[AutopilotCategory]]):
+    """The wire response is a bare list, not a plans envelope."""
+
+
+class ServiceHistoryPlan(CasaModel):
+    """UNVERIFIED item. Known static fields are optional to tolerate drift."""
+
+    id: str | None = None
+    enabled: bool | None = None
+    title: str | None = None
+    selected_cadence: str | None = None
+    next_service_at: int | None = None
+
+
+class ServiceHistoryItem(CasaModel):
+    """UNVERIFIED item from static Codable metadata."""
+
+    task_id: str | None = None
+    task_type: str | None = None
+    task_title: str | None = None
+    task_emoji: str | None = None
+    serviced_at: int | None = None
+    task_hero_image_url: str | None = None
+    task_hero_image_cache_key: str | None = None
+    handyman_job_id: str | None = None
+    vendor_visit_id: str | None = None
+    autopilot_plan_id: str | None = None
+
+
+class InventoryServiceHistoryResponse(CasaModel):
+    autopilot_plans: list[ServiceHistoryPlan]
+    history_items: list[ServiceHistoryItem]
+
+
+class CalendarBusyBlock(CasaModel):
+    """UNVERIFIED block from static Codable metadata."""
+
+    start_time: int | None = None
+    end_time: int | None = None
+    title: str | None = None
+
+
+class CalendarBusyResponse(CasaModel):
+    blocks: list[CalendarBusyBlock]
+    google_status: str
+
+
+class CompletedRequestsResponse(CasaModel):
+    """Empty list observed. RequestCard is the existing static item model."""
+
+    kind: str
+    items: list[RequestCard]
+    pagination: Pagination

casahome/models/membership.py

@@ -0,0 +1,65 @@
+"""Static membership summaries, not billing or lifecycle action contracts.
+
+Fields inferred from the app.
+All fields and response linkage remain UNVERIFIED. Cents/seconds are retained
+as named, without inventing a reporting period, currency or timezone.
+"""
+
+from pydantic import JsonValue
+
+from casahome.models._base import CasaModel
+
+
+class MembershipBenefit(CasaModel):
+    # The app's id type isn't known to be a String, so keep it as JSON.
+    id: JsonValue
+    title: str
+    emoji: str
+    symbol: str
+    description: str
+
+
+class MembershipDetails(CasaModel):
+    name: str
+    amount: str
+    amount_cents: int | None = None
+    interval: str
+    next_billing_date: int | None = None
+    member_since: int | None = None
+    benefits: list[MembershipBenefit] | None = None
+
+
+class MembershipSavingsSummary(CasaModel):
+    total_time_saved_seconds: int
+    total_money_saved_cents: int
+
+
+class MembershipSavingsBreakdown(CasaModel):
+    title: str
+    value: str
+
+
+class MembershipSavingsCategory(CasaModel):
+    type: str
+    label: str
+    color: str
+    preview: str | None = None
+    is_visible: bool
+    time_saved_seconds: int
+    money_saved_cents: int
+    breakdown: list[MembershipSavingsBreakdown]
+
+
+class MembershipSavingsMetadata(CasaModel):
+    id: str
+    created_at: str
+    updated_at: str
+
+
+class MembershipSavings(CasaModel):
+    home_id: str
+    calculated_at: str
+    should_promote: bool
+    summary: MembershipSavingsSummary
+    categories: list[MembershipSavingsCategory]
+    metadata: MembershipSavingsMetadata

casahome/models/paint.py

@@ -0,0 +1,56 @@
+"""Paint library models. Populated integer IDs were observed, not UUIDs."""
+
+from casahome.models._base import CasaModel
+
+
+class PaintBrand(CasaModel):
+    id: int | str
+    color_count: int
+    name: str | None = None
+
+
+class PaintCollection(CasaModel):
+    id: int | str
+    color_count: int
+    name: str | None = None
+
+
+class PaintColor(CasaModel):
+    id: int | str
+    color_name: str | None = None
+    collection_name: str | None = None
+    brand_name: str | None = None
+    color_hex: str | None = None
+
+
+class PaintBrandsResponse(CasaModel):
+    brands: list[PaintBrand]
+
+
+class PaintCollectionsResponse(CasaModel):
+    collections: list[PaintCollection]
+
+
+class PaintColorsResponse(CasaModel):
+    colors: list[PaintColor]
+
+
+class PaintSearchResponse(CasaModel):
+    results: list[PaintColor]
+
+
+class InventoryPaintMatch(CasaModel):
+    """One paint match. VERIFIED populated (live GET, 2026-10)."""
+
+    id: int
+    color_name: str
+    brand_name: str
+    color_hex: str
+    closeness_percentage: float
+
+
+class InventoryPaintMatchesResponse(CasaModel):
+    """Paint matches. VERIFIED envelope (live GET, 2026-10). No match application."""
+
+    matches: list[InventoryPaintMatch]
+    is_manually_added: bool