Metadata-Version: 2.4
Name: nexblue-api
Version: 0.1.0
Summary: Async client for the NexBlue OpenAPI
Project-URL: Homepage, https://github.com/NexBlue-AB/nexblue-api
Project-URL: Repository, https://github.com/NexBlue-AB/nexblue-api
Project-URL: Issues, https://github.com/NexBlue-AB/nexblue-api/issues
Author: NexBlue
Maintainer: NexBlue
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.13
Requires-Dist: aiohttp>=3.10
Provides-Extra: test
Description-Content-Type: text/markdown

# NexBlue API

`nexblue-api` is the official asynchronous Python client for the NexBlue OpenAPI.
It is maintained by NexBlue and currently provides the communication layer used by
the NexBlue Home Assistant integration.

The package handles authentication, access-token refresh, charger discovery,
charger telemetry, and start/stop charging commands. It is deliberately independent
of Home Assistant so it can be reused by other Python applications.

## Requirements

- Python 3.13 or later
- A NexBlue account with access to the NexBlue OpenAPI

Installing this library does not create, grant, or expand access to a NexBlue
account or service.

## Installation

```bash
pip install nexblue-api
```

## Basic usage

Keep credentials outside source code. The example uses environment variables and a
placeholder API base URL supplied by NexBlue.

```python
import asyncio
import os

import aiohttp

from nexblue_api import NexBlueClient


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        client = NexBlueClient(
            session,
            os.environ["NEXBLUE_API_BASE_URL"],
        )

        await client.async_login(
            os.environ["NEXBLUE_USERNAME"],
            os.environ["NEXBLUE_PASSWORD"],
        )

        for charger in await client.async_list_chargers():
            status = await client.async_get_charger_status(charger.serial_number)
            print(charger.serial_number, status.charging_state, status.power_kw)


asyncio.run(main())
```

## Supported operations

- End-user login and refresh-token based access-token renewal
- Charger discovery
- Charger status and telemetry retrieval
- Start charging and stop charging commands
- Typed charger, status, and token models
- Safe exceptions for authentication, connection, rate-limit, offline-device, and
  rejected-command errors

Status values are normalized to the API's documented units: kW, kWh, A, and V.
Charging commands can still be rejected by the API or charger, for example when the
charger is offline or another user is controlling it.

## Credential handling

Do not commit, log, or share usernames, passwords, access tokens, refresh tokens,
or OAuth client credentials.

The client retains tokens only for its active lifetime. Applications that need to
restore a session should persist only the refresh token using their platform's
protected credential storage, then call `async_refresh_access_token`. Do not persist
an end-user password merely to perform automatic logins.

This library does not embed NexBlue OAuth client credentials. Applications using an
external OAuth flow may provide an externally managed access token with
`set_access_token`.

## Development

```bash
python -m pytest -q
python -m build
python -m twine check dist/*
```

Please report bugs through the repository issue tracker. Do not include credentials,
tokens, full API responses, or personally identifiable charger information in issues.

## License

Copyright 2026 NexBlue.

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and
[NOTICE](NOTICE).
