Add first (AI generated) version

Author: iMicknl

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+      - v2/docs
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install docs dependencies
+        run: uv pip install -e ".[docs]"
+
+      - name: Build site
+        run: uv run mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site

docs/api-reference.md

@@ -0,0 +1,13 @@
+::: pyoverkiz.client.OverkizClient
+
+::: pyoverkiz.models
+    options:
+      show_source: false
+
+::: pyoverkiz.enums
+    options:
+      show_source: false
+
+::: pyoverkiz.exceptions
+    options:
+      show_source: false

docs/authentication.md

@@ -0,0 +1,64 @@
+# Authentication
+
+## Cloud username and password
+
+Cloud authentication uses a vendor server from `Server` plus `UsernamePasswordCredentials`.
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import Server
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        print(await client.get_api_version())
+
+
+asyncio.run(main())
+```
+
+## Local token authentication
+
+Local authentication requires a token generated by the official mobile app and a local user on the OverKiz API platform.
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import LocalTokenCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.utils import create_local_server_config
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=create_local_server_config(host="gateway-xxxx.local"),
+        credentials=LocalTokenCredentials("local-token"),
+        verify_ssl=False,
+    ) as client:
+        await client.login()
+        print(await client.get_api_version())
+
+
+asyncio.run(main())
+```
+
+## Token refresh behavior
+
+The client refreshes access tokens as needed during authenticated calls. If you see authentication errors, re-run `login()` before retrying the request.
+
+## Unsupported auth flows
+
+Some vendors use authentication flows that are not supported. In those cases, obtain a local token and use a local server configuration instead.
+
+## Secure storage tips
+
+- Use environment variables or a secret manager for tokens.
+- Avoid hard-coding credentials in source control.
+- Rotate tokens regularly if your vendor supports it.

docs/contribute.md

@@ -0,0 +1,38 @@
+# Contribute
+
+Thanks for contributing to pyOverkiz! This project powers production integrations and values careful changes, clear tests, and thoughtful documentation.
+
+## Development setup
+
+```bash
+uv sync
+```
+
+Install git hooks:
+
+```bash
+uv run prek install
+```
+
+## Tests and linting
+
+```bash
+uv run pytest
+```
+
+```bash
+uv run prek run --all-files
+```
+
+## Project guidelines
+
+- Use Python 3.10–3.13 features and type annotations.
+- Keep absolute imports and avoid relative imports.
+- Preserve existing comments and logging unless your change requires updates.
+- Prefer small, focused changes and add tests when behavior changes.
+
+## Submitting changes
+
+1. Create a feature branch.
+2. Run linting and tests.
+3. Open a pull request with a clear description and context.

docs/core-concepts.md

@@ -0,0 +1,44 @@
+# Core concepts
+
+## Servers and gateways
+
+A server describes where the API calls go. A gateway is the physical hub in your home. Cloud servers route through vendor infrastructure; local servers talk directly to the gateway on your network.
+
+## Setup and devices
+
+The setup describes the current gateway configuration and device inventory. Devices expose metadata like `uiClass` and `widget`, plus a list of current `states`.
+
+## Actions, action groups, and commands
+
+Commands are sent as `Action` objects, grouped into an action group. Each action targets a device URL and a set of commands with parameters.
+
+## States
+
+States are name/value pairs that represent the current device status, such as closure position or temperature.
+
+## Events and listeners
+
+The API uses an event listener that you register once per session. Fetching events drains the server-side buffer.
+
+## Execution model
+
+Commands are executed asynchronously by the platform. You can poll execution state via events or refresh device states after a delay.
+
+## Relationship diagram
+
+```
+Client
+  |
+  |-- Server (cloud or local)
+  |
+  |-- Gateway
+        |
+        |-- Setup
+        |     |
+        |     |-- Devices
+        |            |
+        |            |-- States
+        |            |-- Actions -> Commands -> Parameters
+        |
+        |-- Event Listener -> Events
+```

docs/device-control.md

@@ -0,0 +1,133 @@
+# Device control
+
+## List devices
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import Server
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        devices = await client.get_devices()
+        for device in devices:
+            print(device.label, device.controllable_name)
+
+
+asyncio.run(main())
+```
+
+## Read a state value
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import Server
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        devices = await client.get_devices()
+        device = devices[0]
+        closure_state = next(
+            (state for state in device.states if state.name == "core:ClosureState"),
+            None,
+        )
+        print(closure_state.value if closure_state else None)
+
+
+asyncio.run(main())
+```
+
+## Send a command
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import OverkizCommand, Server
+from pyoverkiz.models import Action, Command
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        await client.execute_action_group(
+            actions=[
+                Action(
+                    device_url="io://1234-5678-1234/12345678",
+                    commands=[
+                        Command(
+                            name=OverkizCommand.SET_CLOSURE,
+                            parameters=[50],
+                        )
+                    ],
+                )
+            ],
+            label="Set closure",
+        )
+
+
+asyncio.run(main())
+```
+
+## Action groups and common patterns
+
+- Use a single action group to batch multiple device commands.
+- Parameters vary by device. Many closure-style devices use 0–100.
+- Thermostat-style devices commonly accept target temperatures.
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import OverkizCommand, Server
+from pyoverkiz.models import Action, Command
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        await client.execute_action_group(
+            actions=[
+                Action(
+                    device_url="io://1234-5678-1234/12345678",
+                    commands=[
+                        Command(
+                            name=OverkizCommand.SET_TARGET_TEMPERATURE,
+                            parameters=[21.5],
+                        )
+                    ],
+                )
+            ],
+            label="Set temperature",
+        )
+
+
+asyncio.run(main())
+```
+
+## Polling vs event-driven
+
+Polling `get_devices()` is simple but can be slower. Event listeners provide faster updates; see the event handling guide for details.

docs/error-handling.md

@@ -0,0 +1,56 @@
+# Error handling
+
+## Common exceptions
+
+- `NotAuthenticatedException`
+- `TooManyRequestsException`
+- `TooManyConcurrentRequestsException`
+- `TooManyExecutionsException`
+- `MaintenanceException`
+- `AccessDeniedToGatewayException`
+- `BadCredentialsException`
+
+## Retry and backoff guidance
+
+Use short, jittered delays for transient errors and re-authenticate on auth failures.
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import Server
+from pyoverkiz.exceptions import (
+    NotAuthenticatedException,
+    TooManyConcurrentRequestsException,
+    TooManyRequestsException,
+)
+
+
+async def fetch_devices_with_retry() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        for attempt in range(5):
+            try:
+                devices = await client.get_devices()
+                print(devices)
+                return
+            except (TooManyRequestsException, TooManyConcurrentRequestsException):
+                await asyncio.sleep(0.5 * (attempt + 1))
+            except NotAuthenticatedException:
+                await client.login()
+
+
+asyncio.run(fetch_devices_with_retry())
+```
+
+## SSL and local certificates
+
+If you use local gateways with `.local` hostnames, you may need `verify_ssl=False` when a trusted certificate is not available.
+
+## Timeouts
+
+For long-running operations, prefer shorter request timeouts with retries rather than a single long timeout.