Metadata-Version: 2.4
Name: ha-xthings-cloud
Version: 1.0.5
Summary: Async Python client for Xthings Cloud API
Author-email: Xthings <dev@xthings.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/XthingsJacobs/ha-xthings-cloud
Project-URL: Repository, https://github.com/XthingsJacobs/ha-xthings-cloud
Project-URL: Issues, https://github.com/XthingsJacobs/ha-xthings-cloud/issues
Keywords: xthings,iot,smart-home,home-assistant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: AsyncIO
Classifier: Topic :: Home Automation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: PyJWT>=2.0.0
Dynamic: license-file

# ha-xthings-cloud

Async Python client for the [Xthings Cloud](https://cloud.xthings.com) API, designed for [Home Assistant](https://www.home-assistant.io/) integration.

## Installation

```bash
pip install ha-xthings-cloud
```

## Usage

### API Client

```python
import aiohttp
from ha_xthings_cloud import XthingsCloudApiClient

async with aiohttp.ClientSession() as session:
    client = XthingsCloudApiClient(session)

    # Login (supports 2FA)
    result = await client.async_login("user@example.com", "password")

    # Get devices
    devices = await client.async_get_devices()

    # Control devices
    await client.async_switch_on("device-uuid")
    await client.async_brite_brightness("device-uuid", 80)
    await client.async_lock_lock("device-uuid")
```

### WebSocket (Real-time Push)

```python
from ha_xthings_cloud import XthingsCloudWebSocket

def on_status(device_uuid, status):
    print(f"Device {device_uuid}: {status}")

async def on_token_expired():
    # refresh token logic
    pass

ws = XthingsCloudWebSocket(session, token, on_status, on_token_expired)
await ws.async_start()
```

### KVS Signaling (Camera WebRTC)

```python
from ha_xthings_cloud import KvsSignalingClient

kvs = KvsSignalingClient(session, region, channel_arn, credentials)
answer_sdp = await kvs.async_get_answer_sdp(offer_sdp, on_ice_candidate=callback)
```

## Features

- Async HTTP client with `aiohttp.ClientSession` injection
- Authentication: login, token refresh, 2FA (email/phone)
- Device control: Switch, Plug, Light (brightness/HS color/color temp), Lock, Camera
- WebSocket: real-time device status push with auto-reconnect
- KVS Signaling: AWS Kinesis Video Streams WebRTC SDP exchange with SigV4 auth
- FRP remote access configuration

## API Reference

### XthingsCloudApiClient

| Method | Description |
|--------|-------------|
| `async_login(email, password, ...)` | Login with optional 2FA |
| `async_refresh_token(refresh_token)` | Refresh auth token |
| `async_get_devices()` | Get device list |
| `async_get_device_status(device_id)` | Get single device status |
| `async_switch_on/off(device_id)` | Switch control |
| `async_plug_on/off(device_id)` | Plug control |
| `async_brite_on/off(device_id)` | Light on/off |
| `async_brite_brightness(device_id, brightness)` | Light brightness (0-100) |
| `async_brite_color(device_id, color)` | Light color (HS/color temp) |
| `async_lock_lock/unlock(device_id)` | Lock control |
| `async_get_camera_webrtc(device_id)` | Get camera KVS credentials |
| `async_get_frp_config(client_id)` | Get FRP remote access config |

### XthingsCloudWebSocket

| Method | Description |
|--------|-------------|
| `async_start()` | Start WebSocket with auto-reconnect |
| `async_stop()` | Stop WebSocket connection |

### KvsSignalingClient

| Method | Description |
|--------|-------------|
| `async_get_answer_sdp(offer_sdp, on_ice_candidate)` | SDP offer/answer exchange |
| `async_send_ice_candidate(candidate, sdp_mid, sdp_mline_index)` | Send ICE candidate |
| `async_get_ice_server_config()` | Get TURN/STUN servers |
| `async_close()` | Close signaling connection |

## License

Apache-2.0