python-casahome 0.2.0__tar.gz

python_casahome-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.env
+.env.*
+!.env.example
+*.har
+traffic/
+*.local.*

python_casahome-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

python_casahome-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_casahome-0.2.0/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.5
+Name: python-casahome
+Version: 0.2.0
+Summary: Unofficial async client for the Casa (getcasa.com) member API
+Author: Borski
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pydantic>=2.5
+Description-Content-Type: text/markdown
+
+# python-casahome
+
+Async Python client for the [Casa](https://getcasa.com) home membership API.
+
+Unofficial. Not affiliated with or endorsed by Casa.
+
+## Status
+
+Version 0.2.0, alpha.
+
+- The library is read-heavy. Most methods are GETs, and most of those have been
+  confirmed against live traffic.
+- A few write methods exist. They are unverified and haven't been exercised
+  against the real backend. Treat them as experimental.
+- Endpoint shapes were inferred from the iOS app and confirmed against live
+  traffic where marked. Casa can change its private API at any time.
+
+## Install
+
+PyPI isn't set up yet. Install from GitHub:
+
+```
+pip install "python-casahome @ git+https://github.com/borski/python-casahome@v0.2.0"
+```
+
+Requires Python 3.11 or newer.
+
+## Authentication
+
+Casa signs members in with Firebase phone auth, and SMS sign-in only works from
+the real app. This library starts from a Firebase refresh token instead and
+exchanges it for short-lived ID tokens.
+
+Casa offers no official way to export that token. You obtain your own refresh
+token from your own Casa app session, for example by inspecting your own app's
+traffic during login and reading `refreshToken` from the Firebase token
+response.
+
+Treat the refresh token like a password. Anyone holding it can act as you.
+Keep it in a password manager or secret store, never in source control.
+
+The token doesn't expire on a timer, but Firebase can rotate it. Pass
+`on_refresh_token_rotated` to `FirebaseAuth` (sync or async) and persist the new
+value when it fires.
+
+## Quick start
+
+```python
+import asyncio
+
+from casahome import CasaApi
+
+
+async def main() -> None:
+    async with CasaApi.create("YOUR_REFRESH_TOKEN") as api:
+        me = await api.bootstrap()
+        for home in me.homes:
+            print(home.display_address, home.status)
+            weather = await api.weather(home.id)
+            print(weather)
+
+
+asyncio.run(main())
+```
+
+If you already own an `aiohttp.ClientSession` (for example in Home Assistant),
+build the pieces yourself:
+
+```python
+from casahome import CasaApi, CasaClient, FirebaseAuth
+
+auth = FirebaseAuth(session, refresh_token, on_refresh_token_rotated=save_token)
+api = CasaApi(
+    CasaClient(session, auth),
+    device_id=stored_device_id,
+    timezone="America/Los_Angeles",
+)
+```
+
+`bootstrap` registers a device with Casa. Long-lived callers should persist
+`api.device_id` and pass it back on the next start. Otherwise every restart adds
+a new device to the account.
+
+A runnable example lives in `examples/bootstrap.py`:
+
+```
+CASA_REFRESH_TOKEN=... uv run examples/bootstrap.py
+```
+
+## Coverage
+
+Each method's docstring starts with `VERIFIED` or `UNVERIFIED`.
+`casahome.is_unverified(api.some_method)` reports the same thing at runtime.
+
+The "Live-confirmed" column means:
+
+- **yes**: the path, method, response envelope and list item shapes were seen
+  in live traffic.
+- **partial**: the path, method and envelope were seen, but lists came back
+  empty or items are kept as opaque JSON. Item models are inferred.
+- **no**: inferred from the app only. Not seen working live.
+
+The envelope is the top-level response keys. Item shape is the structure of
+elements inside lists. All live confirmation dates from 2026-10.
+
+### Reads
+
+| Method | Live-confirmed | Notes |
+|---|---|---|
+| `bootstrap` | yes | Profile, homes, badge counts, app update info. |
+| `onboarding_details` | yes | Raw dict, or `None` on 304. |
+| `onboarding_details_typed` | yes | Typed version of the above. |
+| `onboarding_availability` | yes | |
+| `home_details` | yes | Stories, rooms, inventory entities. |
+| `inventory_item` | yes | One entity. |
+| `inventory_makes` | yes | |
+| `inventory_enums` | yes | Takes a property's `enum_type` key, such as `light_fixture_type`. |
+| `inventory_paint_matches` | yes | |
+| `inventory_service_history` | partial | Room and home targets seen. Entity target untested. |
+| `room_types` | yes | |
+| `room_image_options` | yes | |
+| `room_image_candidates` | yes | |
+| `matterport_images` | yes | |
+| `badge_counts` | yes | |
+| `weather` | yes | |
+| `credits_summary` | yes | |
+| `home_feed` | yes | `props` varies by card template and stays a JSON dict. |
+| `home_members` | yes | |
+| `schedule_preferences` | yes | |
+| `notification_settings` | yes | |
+| `access_preferences` | partial | Option values not seen populated. |
+| `autopilot_plans` | yes | |
+| `paint_brands`, `paint_collections`, `paint_colors`, `paint_search` | yes | |
+| `suggested_todos` | yes | Question rounds and destination stay opaque. |
+| `todo_details` | yes | Same caveat. |
+| `document_types` | yes | |
+| `help_center_bundle` | yes | Only `member_ios` tested. |
+| `release_notes` | yes | |
+| `release_notes_diff` | yes | |
+| `casa_ai_bootstrap` | partial | Messages not seen populated. |
+| `casa_ai_messages` | partial | |
+| `requests_tab` | partial | |
+| `completed_requests` | partial | |
+| `calendar` | partial | Bounds sent as epoch seconds. |
+| `calendar_busy` | partial | |
+| `calendar_sync` | partial | |
+| `mailbox`, `mail_items`, `packages` | partial | |
+| `documents` | partial | Query parameters untested. |
+| `work_document_source` | partial | Only the `todo_id` selector tested. |
+| `vehicles` | partial | |
+| `utilities_insights` | partial | |
+| `purchases` | partial | |
+| `property_taxes` | partial | |
+| `recurring_vendor_categories` | yes | |
+| `recurring_vendors` | partial | |
+| `bookable_handyman_tasks` | partial | Items stay opaque JSON. |
+| `referral_code` | partial | `display` and `referred_homes` stay opaque JSON. |
+| `request_details` | no | |
+| `membership_info` | no | Returned 404 in testing. |
+| `membership_savings` | no | Returned 404 in testing. |
+| `availability_request_details` | no | |
+| `document_details` | no | |
+| `document_suggestions` | no | |
+| `document_structure_suggestions` | no | |
+| `request_purchases` | no | |
+| `task_details` | no | |
+| `vendor_visit_details` | no | |
+| `vendor_visit_autopilot_plan` | no | |
+| `vendor_visit_calls` | no | |
+| `vendor_visit_conversation` | no | |
+| `vendor_visit_purchases` | no | |
+| `casa_ai_events` | partial | Opt-in SSE stream. Transport confirmed, event payloads untested. |
+
+### Writes
+
+| Method | Live-confirmed |
+|---|---|
+| `create_todo_result` | no |
+| `create_todo` | no |
+| `send_request_message` | no |
+| `update_entity_properties` | no |
+
+## Models
+
+Import models from `casahome.models`. Unknown response fields are kept in
+`model_extra` rather than dropped, so new server fields don't break parsing.
+A response that doesn't match the expected shape raises `CasaResponseError`.
+
+Identifier arguments are checked before any request. They must be nonempty
+path-safe segments (letters, digits, `.`, `_`, `~`, `-`). IDs aren't trimmed,
+lowercased or forced to UUIDs.
+
+Responses can contain personal data: names, contact details, messages,
+documents and purchase info. Avoid logging whole models. URLs in responses are
+returned as data. The library never follows them.
+
+## Writes
+
+The write methods are unverified. Their request bodies were inferred from the
+app and have not been exercised against the live backend. Nothing is sent until
+you await a write method.
+
+- Each write is sent exactly once. There is no retry, including on 401. The ID
+  token is refreshed before the request, and a 401 raises `CasaAuthError`.
+  Deciding whether to repeat is up to you.
+- If the response fails to parse, the server may still have performed the
+  action. Don't assume a parse error means it's safe to repeat.
+- Request bodies are strict Pydantic models. Unknown fields and invalid values
+  raise `CasaRequestError` before any I/O. Free-text fields are capped at
+  10,000 characters.
+- Optional fields set to `None` are omitted from the JSON. Empty strings and
+  empty lists are sent as given.
+- `send_request_message` only allows the `member` sender role.
+- `create_todo_result` returns the full envelope, including
+  `needs_support_confirmation`. `create_todo` is the older helper that returns
+  just the todo.
+
+## CasaAI event stream
+
+`api.casa_ai_events(home_id, after=None)` is an opt-in async generator over the
+CasaAI server-sent event stream. It doesn't reconnect on its own. Close it with
+`contextlib.aclosing` if you stop early:
+
+```python
+from contextlib import aclosing
+
+from casahome.streaming import CasaAIResyncRequiredEvent, CasaAIThreadUpdateEvent
+
+async with aclosing(api.casa_ai_events(home_id, after=saved_cursor)) as events:
+    async for event in events:
+        saved_cursor = event.id
+        if isinstance(event, CasaAIResyncRequiredEvent):
+            break  # Reload state, then subscribe again.
+        if isinstance(event, CasaAIThreadUpdateEvent):
+            update = event.payload  # Opaque JSON.
+```
+
+Lines are capped at 64 KiB and events at 256 KiB. A 401 refreshes the token and
+retries the GET once.
+
+## Development
+
+```
+uv sync
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src tests
+```
+
+Tests use synthetic data and a loopback test server. They make no network calls
+and need no credentials.
+
+## License
+
+MIT. See `LICENSE`.

python_casahome-0.2.0/README.md

@@ -0,0 +1,256 @@
+# python-casahome
+
+Async Python client for the [Casa](https://getcasa.com) home membership API.
+
+Unofficial. Not affiliated with or endorsed by Casa.
+
+## Status
+
+Version 0.2.0, alpha.
+
+- The library is read-heavy. Most methods are GETs, and most of those have been
+  confirmed against live traffic.
+- A few write methods exist. They are unverified and haven't been exercised
+  against the real backend. Treat them as experimental.
+- Endpoint shapes were inferred from the iOS app and confirmed against live
+  traffic where marked. Casa can change its private API at any time.
+
+## Install
+
+PyPI isn't set up yet. Install from GitHub:
+
+```
+pip install "python-casahome @ git+https://github.com/borski/python-casahome@v0.2.0"
+```
+
+Requires Python 3.11 or newer.
+
+## Authentication
+
+Casa signs members in with Firebase phone auth, and SMS sign-in only works from
+the real app. This library starts from a Firebase refresh token instead and
+exchanges it for short-lived ID tokens.
+
+Casa offers no official way to export that token. You obtain your own refresh
+token from your own Casa app session, for example by inspecting your own app's
+traffic during login and reading `refreshToken` from the Firebase token
+response.
+
+Treat the refresh token like a password. Anyone holding it can act as you.
+Keep it in a password manager or secret store, never in source control.
+
+The token doesn't expire on a timer, but Firebase can rotate it. Pass
+`on_refresh_token_rotated` to `FirebaseAuth` (sync or async) and persist the new
+value when it fires.
+
+## Quick start
+
+```python
+import asyncio
+
+from casahome import CasaApi
+
+
+async def main() -> None:
+    async with CasaApi.create("YOUR_REFRESH_TOKEN") as api:
+        me = await api.bootstrap()
+        for home in me.homes:
+            print(home.display_address, home.status)
+            weather = await api.weather(home.id)
+            print(weather)
+
+
+asyncio.run(main())
+```
+
+If you already own an `aiohttp.ClientSession` (for example in Home Assistant),
+build the pieces yourself:
+
+```python
+from casahome import CasaApi, CasaClient, FirebaseAuth
+
+auth = FirebaseAuth(session, refresh_token, on_refresh_token_rotated=save_token)
+api = CasaApi(
+    CasaClient(session, auth),
+    device_id=stored_device_id,
+    timezone="America/Los_Angeles",
+)
+```
+
+`bootstrap` registers a device with Casa. Long-lived callers should persist
+`api.device_id` and pass it back on the next start. Otherwise every restart adds
+a new device to the account.
+
+A runnable example lives in `examples/bootstrap.py`:
+
+```
+CASA_REFRESH_TOKEN=... uv run examples/bootstrap.py
+```
+
+## Coverage
+
+Each method's docstring starts with `VERIFIED` or `UNVERIFIED`.
+`casahome.is_unverified(api.some_method)` reports the same thing at runtime.
+
+The "Live-confirmed" column means:
+
+- **yes**: the path, method, response envelope and list item shapes were seen
+  in live traffic.
+- **partial**: the path, method and envelope were seen, but lists came back
+  empty or items are kept as opaque JSON. Item models are inferred.
+- **no**: inferred from the app only. Not seen working live.
+
+The envelope is the top-level response keys. Item shape is the structure of
+elements inside lists. All live confirmation dates from 2026-10.
+
+### Reads
+
+| Method | Live-confirmed | Notes |
+|---|---|---|
+| `bootstrap` | yes | Profile, homes, badge counts, app update info. |
+| `onboarding_details` | yes | Raw dict, or `None` on 304. |
+| `onboarding_details_typed` | yes | Typed version of the above. |
+| `onboarding_availability` | yes | |
+| `home_details` | yes | Stories, rooms, inventory entities. |
+| `inventory_item` | yes | One entity. |
+| `inventory_makes` | yes | |
+| `inventory_enums` | yes | Takes a property's `enum_type` key, such as `light_fixture_type`. |
+| `inventory_paint_matches` | yes | |
+| `inventory_service_history` | partial | Room and home targets seen. Entity target untested. |
+| `room_types` | yes | |
+| `room_image_options` | yes | |
+| `room_image_candidates` | yes | |
+| `matterport_images` | yes | |
+| `badge_counts` | yes | |
+| `weather` | yes | |
+| `credits_summary` | yes | |
+| `home_feed` | yes | `props` varies by card template and stays a JSON dict. |
+| `home_members` | yes | |
+| `schedule_preferences` | yes | |
+| `notification_settings` | yes | |
+| `access_preferences` | partial | Option values not seen populated. |
+| `autopilot_plans` | yes | |
+| `paint_brands`, `paint_collections`, `paint_colors`, `paint_search` | yes | |
+| `suggested_todos` | yes | Question rounds and destination stay opaque. |
+| `todo_details` | yes | Same caveat. |
+| `document_types` | yes | |
+| `help_center_bundle` | yes | Only `member_ios` tested. |
+| `release_notes` | yes | |
+| `release_notes_diff` | yes | |
+| `casa_ai_bootstrap` | partial | Messages not seen populated. |
+| `casa_ai_messages` | partial | |
+| `requests_tab` | partial | |
+| `completed_requests` | partial | |
+| `calendar` | partial | Bounds sent as epoch seconds. |
+| `calendar_busy` | partial | |
+| `calendar_sync` | partial | |
+| `mailbox`, `mail_items`, `packages` | partial | |
+| `documents` | partial | Query parameters untested. |
+| `work_document_source` | partial | Only the `todo_id` selector tested. |
+| `vehicles` | partial | |
+| `utilities_insights` | partial | |
+| `purchases` | partial | |
+| `property_taxes` | partial | |
+| `recurring_vendor_categories` | yes | |
+| `recurring_vendors` | partial | |
+| `bookable_handyman_tasks` | partial | Items stay opaque JSON. |
+| `referral_code` | partial | `display` and `referred_homes` stay opaque JSON. |
+| `request_details` | no | |
+| `membership_info` | no | Returned 404 in testing. |
+| `membership_savings` | no | Returned 404 in testing. |
+| `availability_request_details` | no | |
+| `document_details` | no | |
+| `document_suggestions` | no | |
+| `document_structure_suggestions` | no | |
+| `request_purchases` | no | |
+| `task_details` | no | |
+| `vendor_visit_details` | no | |
+| `vendor_visit_autopilot_plan` | no | |
+| `vendor_visit_calls` | no | |
+| `vendor_visit_conversation` | no | |
+| `vendor_visit_purchases` | no | |
+| `casa_ai_events` | partial | Opt-in SSE stream. Transport confirmed, event payloads untested. |
+
+### Writes
+
+| Method | Live-confirmed |
+|---|---|
+| `create_todo_result` | no |
+| `create_todo` | no |
+| `send_request_message` | no |
+| `update_entity_properties` | no |
+
+## Models
+
+Import models from `casahome.models`. Unknown response fields are kept in
+`model_extra` rather than dropped, so new server fields don't break parsing.
+A response that doesn't match the expected shape raises `CasaResponseError`.
+
+Identifier arguments are checked before any request. They must be nonempty
+path-safe segments (letters, digits, `.`, `_`, `~`, `-`). IDs aren't trimmed,
+lowercased or forced to UUIDs.
+
+Responses can contain personal data: names, contact details, messages,
+documents and purchase info. Avoid logging whole models. URLs in responses are
+returned as data. The library never follows them.
+
+## Writes
+
+The write methods are unverified. Their request bodies were inferred from the
+app and have not been exercised against the live backend. Nothing is sent until
+you await a write method.
+
+- Each write is sent exactly once. There is no retry, including on 401. The ID
+  token is refreshed before the request, and a 401 raises `CasaAuthError`.
+  Deciding whether to repeat is up to you.
+- If the response fails to parse, the server may still have performed the
+  action. Don't assume a parse error means it's safe to repeat.
+- Request bodies are strict Pydantic models. Unknown fields and invalid values
+  raise `CasaRequestError` before any I/O. Free-text fields are capped at
+  10,000 characters.
+- Optional fields set to `None` are omitted from the JSON. Empty strings and
+  empty lists are sent as given.
+- `send_request_message` only allows the `member` sender role.
+- `create_todo_result` returns the full envelope, including
+  `needs_support_confirmation`. `create_todo` is the older helper that returns
+  just the todo.
+
+## CasaAI event stream
+
+`api.casa_ai_events(home_id, after=None)` is an opt-in async generator over the
+CasaAI server-sent event stream. It doesn't reconnect on its own. Close it with
+`contextlib.aclosing` if you stop early:
+
+```python
+from contextlib import aclosing
+
+from casahome.streaming import CasaAIResyncRequiredEvent, CasaAIThreadUpdateEvent
+
+async with aclosing(api.casa_ai_events(home_id, after=saved_cursor)) as events:
+    async for event in events:
+        saved_cursor = event.id
+        if isinstance(event, CasaAIResyncRequiredEvent):
+            break  # Reload state, then subscribe again.
+        if isinstance(event, CasaAIThreadUpdateEvent):
+            update = event.payload  # Opaque JSON.
+```
+
+Lines are capped at 64 KiB and events at 256 KiB. A 401 refreshes the token and
+retries the GET once.
+
+## Development
+
+```
+uv sync
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src tests
+```
+
+Tests use synthetic data and a loopback test server. They make no network calls
+and need no credentials.
+
+## License
+
+MIT. See `LICENSE`.

python_casahome-0.2.0/examples/bootstrap.py

@@ -0,0 +1,53 @@
+"""Print a summary of your Casa account.
+
+    CASA_REFRESH_TOKEN=... uv run examples/bootstrap.py [--show-token]
+    op run --env-file=.env -- uv run examples/bootstrap.py
+
+Only calls the Firebase token endpoint and the VERIFIED bootstrap endpoint.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+from casahome import CasaApi, CasaError
+
+
+async def main(show_token: bool) -> int:
+    token = os.environ.get("CASA_REFRESH_TOKEN", "").strip()
+    if not token:
+        print("Set CASA_REFRESH_TOKEN", file=sys.stderr)
+        return 2
+    try:
+        async with CasaApi.create(token) as api:
+            me = await api.bootstrap()
+            rotated = api.client.auth.refresh_token
+    except CasaError as err:
+        print(f"{type(err).__name__}: {err}", file=sys.stderr)
+        return 1
+
+    print(f"Hi {me.first_name}. {len(me.homes)} home(s).")
+    for home in me.homes:
+        print(f"  {home.id}: status={home.status} plan_state={home.plan_state}")
+        if home.badge_counts:
+            print(f"    badges: {home.badge_counts.features} (total {home.badge_counts.total})")
+        if home.pending_agreements:
+            names = ", ".join(a.name for a in home.pending_agreements)
+            print(f"    pending agreements: {names}")
+    if me.app_update:
+        print(f"App update required: {me.app_update.force_update_required}")
+    if show_token:
+        changed = "rotated" if rotated != token else "unchanged"
+        print(f"Refresh token ({changed}): {rotated}")
+    elif rotated != token:
+        print("Note: Firebase rotated the refresh token. Rerun with --show-token to see it.")
+    return 0
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--show-token", action="store_true")
+    sys.exit(asyncio.run(main(parser.parse_args().show_token)))

python_casahome-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "python-casahome"
+version = "0.2.0"
+description = "Unofficial async client for the Casa (getcasa.com) member API"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Borski" }]
+requires-python = ">=3.11"
+dependencies = [
+    "aiohttp>=3.9",
+    "pydantic>=2.5",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10",
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/casahome"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]