Metadata-Version: 2.4
Name: tiremo-sdk-client
Version: 0.1.4
Summary: Python client for the TIREMO SDK REST and live WebSocket APIs
Project-URL: Homepage, https://docs.tiremo.ai/developer-guide/sdk-live-data
Project-URL: Repository, https://github.com/Empa-Electronics/TIREMO-SDK-CLIENT
Project-URL: Issues, https://github.com/Empa-Electronics/TIREMO-SDK-CLIENT/issues
Author: Empa Electronics
License-Expression: ISC
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# tiremo-sdk-client

Async Python client for the [TIREMO SDK](https://github.com/Empa-Electronics/TIREMO-SDK). REST bootstrap plus a WebSocket live channel for telemetry, presence, and alarms.

Requires **Python 3.10+**.

## Documentation

| Topic | Link |
| --- | --- |
| SDK Live Data | [docs.tiremo.ai/developer-guide/sdk-live-data](https://docs.tiremo.ai/developer-guide/sdk-live-data) |
| API Key Security | [docs.tiremo.ai/developer-guide/sdk-api-key-security](https://docs.tiremo.ai/developer-guide/sdk-api-key-security) |

## Getting started

### 1. Install

```bash
pip install tiremo-sdk-client
```

From source (development):

```bash
cd client-python
make venv lint
```

### 2. Get an API key

Create a product-scoped API key in the Tiremo Platform **Administration → API Credentials** UI.

Use a **secret** key for backend services. Use `create_live_token()` when handing off to untrusted clients.

### 3. Create a client

```python
from tiremo_sdk import TiremoClient

client = TiremoClient(
    api_key="your-api-key",
    base_url="https://sdk.tiremo.ai",
)
```

All methods are **async** — run them inside `asyncio.run()` or your async framework.

### 4. Choose a live connection mode

| Method | When to use |
| --- | --- |
| `connect_live_with_secret_key()` | Trusted backend scripts and workers |
| `create_live_token()` + `connect_live_with_token()` | Serving browser or mobile clients |

## Usage examples

### `TiremoClient` — REST

#### `get_telemetry_latest(device_identifier, *, keys=None)`

```python
latest = await client.get_telemetry_latest(
    "cameradevice9",
    keys=["temperature", "humidity"],
)

print(latest["deviceIdentifier"])
print(latest["timestamp"])
print(latest["data"]["temperature"])
```

Pass `keys=None` to fetch all keys on the latest point.

#### `create_live_token()`

```python
token_response = await client.create_live_token()
token = token_response["token"]
expires_at = token_response["expiresAt"]
```

#### `connect_live_with_token(token)`

```python
live = client.connect_live_with_token(token)
await live.connect()
```

#### `connect_live_with_secret_key()`

```python
live = client.connect_live_with_secret_key()
await live.connect()
```

### `TiremoLiveClient` — WebSocket

#### `connect()` / `disconnect()`

```python
await live.connect()
# ...
await live.disconnect()
```

#### `on(event, handler)`

Handlers may be sync or async. Returns an unsubscribe callable.

```python
async def on_telemetry(event: dict) -> None:
    print(event["data"])

live.on("telemetry", on_telemetry)

live.on("connected", lambda e: print(e["productIdentifier"]))
live.on("presence", lambda e: print(e["deviceIdentifier"], e["isOnline"]))
live.on("alarm", lambda e: print(e["alarmType"], e["severity"]))
live.on("error", lambda e: print(e["code"], e["message"]))
```

#### `subscribe_telemetry(subscription_id, device_identifier, *, keys=None)`

```python
await live.subscribe_telemetry(
    "temp-sub",
    "cameradevice9",
    keys=["temperature"],
)
```

#### `subscribe_presence(subscription_id, device_identifier)`

```python
await live.subscribe_presence("presence-sub", "cameradevice9")
```

#### `subscribe_alarm(subscription_id, device_identifier)`

```python
await live.subscribe_alarm("alarm-sub", "cameradevice9")
```

#### `unsubscribe(subscription_id)`

```python
await live.unsubscribe("temp-sub")
```

Ping/pong heartbeats are handled automatically.

## Full example

```python
import asyncio

from tiremo_sdk import TiremoClient


async def main() -> None:
    client = TiremoClient(
        api_key="your-api-key",
        base_url="https://sdk.tiremo.ai",
    )

    latest = await client.get_telemetry_latest("cameradevice9", keys=["temperature"])
    print("Latest:", latest["data"])

    live = client.connect_live_with_secret_key()

    async def on_connected(_event: dict) -> None:
        await live.subscribe_telemetry("temp", "cameradevice9", keys=["temperature"])

    async def on_telemetry(event: dict) -> None:
        print("Live:", event["data"])

    live.on("connected", on_connected)
    live.on("telemetry", on_telemetry)

    await live.connect()
    await asyncio.sleep(60)
    await live.disconnect()


asyncio.run(main())
```

## Related packages

| Package | Use case |
| --- | --- |
| [`@empa-electronics/tiremo-sdk-client-js`](https://www.npmjs.com/package/@empa-electronics/tiremo-sdk-client-js) | Browser / bundler |
| [`@empa-electronics/tiremo-sdk-client-node`](https://www.npmjs.com/package/@empa-electronics/tiremo-sdk-client-node) | Node.js 18+ |

## License

ISC — [Empa Electronics](https://github.com/Empa-Electronics)
