pynissan 0.1.0__tar.gz

pynissan-0.1.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to `pynissan` are documented in this file.
+
+The project follows [Semantic Versioning](https://semver.org/).
+
+<!-- version list -->
+
+## v0.1.0 (2026-08-01)
+
+### Bug Fixes
+
+- Harden command status and enum inputs
+  ([`415326b`](https://github.com/bvdcode/nissan-connect-sdk/commit/415326b528332d6c835c9a6a3ea6743a39d15dd4))
+
+- Surface polling timeouts consistently
+  ([`527172e`](https://github.com/bvdcode/nissan-connect-sdk/commit/527172ee532c4d7955ba2d3cbe7b44540962ea66))
+
+### Continuous Integration
+
+- Automate semantic releases
+  ([`f2bb388`](https://github.com/bvdcode/nissan-connect-sdk/commit/f2bb38822fe8aaba230e441a4201ba74898c421a))
+
+- Automate tagged releases
+  ([`2d63335`](https://github.com/bvdcode/nissan-connect-sdk/commit/2d6333561aa02ee60744d03dce4e3673722855c9))
+
+- Automate validation and PyPI publishing
+  ([`697274a`](https://github.com/bvdcode/nissan-connect-sdk/commit/697274aeb91d95da5e39bc529bec8a479efcd99a))
+
+- Enforce Python module size limit
+  ([`5192435`](https://github.com/bvdcode/nissan-connect-sdk/commit/5192435c10fdb132f474842c260b3b03bd63053f))
+
+- Install release build tooling
+  ([`c5cf9c2`](https://github.com/bvdcode/nissan-connect-sdk/commit/c5cf9c26dd637f170897d95e1d7bc5affbf7b792))
+
+### Documentation
+
+- Describe protected request configuration
+  ([`f304cf8`](https://github.com/bvdcode/nissan-connect-sdk/commit/f304cf84e596a22bbd35dcb977e41dc7cc9937c2))
+
+- Prepare the package for release
+  ([`1087b74`](https://github.com/bvdcode/nissan-connect-sdk/commit/1087b74f2563a90b98c3f9103b881637cc8c7d8b))
+
+### Features
+
+- Add the pynissan async client
+  ([`21f8dbc`](https://github.com/bvdcode/nissan-connect-sdk/commit/21f8dbcd439c68afa1e72c4ae8b889fddccd22cb))
+
+- Support protected onboarding requests
+  ([`c68dce3`](https://github.com/bvdcode/nissan-connect-sdk/commit/c68dce32dfa741c34144da1631d967808f1e95e3))
+
+### Refactoring
+
+- Keep transport internals private
+  ([`92e4c9c`](https://github.com/bvdcode/nissan-connect-sdk/commit/92e4c9cf5b0bff599091edc87bc4a6f5f59a47f0))
+
+- Split account feature parsers
+  ([`397dd50`](https://github.com/bvdcode/nissan-connect-sdk/commit/397dd505b9fe2931a56a42242842ff430aac946c))
+
+- Split client by service domain
+  ([`26d71a4`](https://github.com/bvdcode/nissan-connect-sdk/commit/26d71a414c597b833626740b2357230f13ded855))
+
+- Split core domain models
+  ([`1df47fb`](https://github.com/bvdcode/nissan-connect-sdk/commit/1df47fb07f5eea54b07ff8aaa99964020cedb6e7))
+
+- Split oversized test modules
+  ([`50247a8`](https://github.com/bvdcode/nissan-connect-sdk/commit/50247a8368d2a884443f37bf0cb84153864d1d67))
+
+- Split vehicle service parsers
+  ([`9408521`](https://github.com/bvdcode/nissan-connect-sdk/commit/9408521515e8e225f9864eb5ec7dc05640f53a1c))
+
+### Testing
+
+- Cover connected vehicle operations
+  ([`6129b49`](https://github.com/bvdcode/nissan-connect-sdk/commit/6129b49a1b451eae5bddf42c9761b3fdbd08b275))

pynissan-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Contributions that improve correctness, type safety, test coverage, or supported vehicle
+features are welcome.
+
+## Development setup
+
+```bash
+python -m venv .venv
+python -m pip install -e ".[test]"
+```
+
+Run the complete quality gate before opening a pull request:
+
+```bash
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python scripts/check_file_size.py
+python -m pytest
+python -m build
+```
+
+## Code guidelines
+
+- Add precise type hints to all new functions, methods, and attributes.
+- Add concise English docstrings to public classes, functions, and methods.
+- Keep request serialization, transport, response parsing, and domain models separate.
+- Preserve nullable fields and unknown upstream values instead of inventing defaults.
+- Add focused tests for request variables, response parsing, errors, and read-only behavior.
+- Keep state-changing operations behind the client's read-only guard.
+- Keep handwritten Python files at or below 500 non-empty, non-comment lines. Prefer
+  300–400 lines and split by responsibility before reaching the hard limit.
+
+The only size-limit exceptions are the public export barrel in `src/pynissan/__init__.py`
+and the declarative GraphQL document catalog in `src/pynissan/operations.py`.
+
+## Test data
+
+Use neutral fixtures. Never commit credentials, OAuth tokens, vehicle identifiers, account
+details, private URLs, or captured customer responses.
+
+## Pull requests
+
+Keep each pull request focused and describe the product behavior it changes. Include tests for
+new behavior and note any vehicle capability required to exercise it.
+
+Pull requests are squash merged. Use a Conventional Commit title because the resulting merge
+commit controls versioning and becomes the release-note entry:
+
+- `feat:` for a new public capability and a minor release.
+- `fix:` or `perf:` for a patch release.
+- `BREAKING CHANGE:` in the body for a major release.
+- `build:`, `chore:`, `ci:`, `docs:`, `refactor:`, `style:`, or `test:` for changes that do not
+  release by themselves.
+
+Do not edit the project version or create version tags manually. The release workflow updates the
+version and changelog after a releasable commit reaches `main`.

pynissan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vadim Belov
+
+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.

pynissan-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include scripts *.py

pynissan-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: pynissan
+Version: 0.1.0
+Summary: Independent async Python client for MyNISSAN connected vehicles
+Author: Vadim Belov
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/bvdcode/nissan-connect-sdk/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/bvdcode/nissan-connect-sdk/tree/main/docs
+Project-URL: Issues, https://github.com/bvdcode/nissan-connect-sdk/issues
+Project-URL: Repository, https://github.com/bvdcode/nissan-connect-sdk
+Keywords: ariya,asyncio,connected-car,home-assistant,nissan
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.12
+Provides-Extra: test
+Requires-Dist: build<2,>=1.5; extra == "test"
+Requires-Dist: mypy<3,>=2.3; extra == "test"
+Requires-Dist: python-semantic-release<11,>=10.6; extra == "test"
+Requires-Dist: pytest<10,>=9.1; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=1.4; extra == "test"
+Requires-Dist: ruff<0.17,>=0.16; extra == "test"
+Requires-Dist: twine<7,>=6.2; extra == "test"
+Dynamic: license-file
+
+# pynissan
+
+[![CI](https://github.com/bvdcode/nissan-connect-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/bvdcode/nissan-connect-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pynissan.svg)](https://pypi.org/project/pynissan/)
+[![Python](https://img.shields.io/pypi/pyversions/pynissan.svg)](https://pypi.org/project/pynissan/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`pynissan` is an independently maintained async Python client for MyNISSAN connected
+vehicle services. It provides a typed API for vehicle telemetry, charging, climate,
+remote commands, account data, and connected-service features.
+
+The client currently supports United States MyNISSAN accounts and includes Nissan Ariya
+telemetry and remote-control support.
+
+## Highlights
+
+- Fully async I/O built on `aiohttp`.
+- Typed, immutable response models and a `py.typed` marker.
+- Cached vehicle, battery, charging, climate, door, location, tire, and mileage data.
+- Charging, climate, lock, light, horn, engine, location, and status-refresh commands.
+- Climate and charge schedules, vehicle capabilities, alerts, maintenance, and history.
+- Automatic access-token refresh with a callback for persisting replacement tokens.
+- Static or refreshable request proof for protected service operations.
+- Read-only mode enabled by default for safe discovery and monitoring.
+- No dependency on Home Assistant.
+
+## Installation
+
+```bash
+python -m pip install pynissan
+```
+
+Python 3.12 or newer is required.
+
+## Quick start
+
+The caller owns the `aiohttp.ClientSession` and decides how credentials and reusable tokens
+are stored.
+
+```python
+from aiohttp import ClientSession
+
+from pynissan import Country, NissanClient, Tokens
+
+
+async def save_tokens(tokens: Tokens) -> None:
+    """Persist replacement tokens in the application's secure storage."""
+
+
+async def read_vehicle(email: str, password: str) -> None:
+    async with ClientSession() as session:
+        client = NissanClient(
+            session,
+            country=Country.US,
+            token_listener=save_tokens,
+        )
+        await client.async_authenticate(email, password)
+
+        vehicles = await client.async_get_vehicles()
+        if not vehicles:
+            return
+
+        status = await client.async_get_vehicle_status(vehicles[0].vin)
+        if status.battery is not None:
+            print(status.battery.level)
+            print(status.battery.is_charging)
+```
+
+Supply previously saved tokens to avoid signing in again:
+
+```python
+client = NissanClient(
+    session,
+    country=Country.US,
+    tokens=saved_tokens,
+    token_listener=save_tokens,
+)
+```
+
+The client refreshes expired tokens before a request and publishes the replacement token set
+through `token_listener`.
+
+Protected operations accept a `RequestProof` value or an async `RequestProofProvider`. The
+provider is called with `False` for a current value and with `True` when the service rejects a
+stale value.
+
+## Read-only safety
+
+`NissanClient` starts in read-only mode. Queries work normally, while methods that change
+vehicle or account state raise `ReadOnlyError` before any network request is sent.
+
+```python
+from pynissan import Country, NissanClient
+
+client = NissanClient(
+    session,
+    country=Country.US,
+    tokens=saved_tokens,
+    read_only=False,
+)
+```
+
+Enable write access only for an explicit user action. Remote commands return a typed request
+that can be polled until Nissan reports a terminal status.
+
+```python
+from pynissan import ClimateSettings, TemperatureUnit
+
+request = await client.async_start_climate(
+    vin,
+    ClimateSettings(72, TemperatureUnit.FAHRENHEIT),
+)
+result = await client.async_wait_for_service_request(vin, request)
+```
+
+## Charging state
+
+Battery status distinguishes the cable and charging states and includes the server-provided
+remaining charge time.
+
+```python
+battery = await client.async_get_vehicle_battery_status(vin)
+if battery is not None:
+    print(battery.level)
+    print(battery.is_plugged_in)
+    print(battery.is_charging)
+    print(battery.remaining_charge_time)
+```
+
+## Errors
+
+All package exceptions inherit from `NissanError`:
+
+- `AuthenticationError` for sign-in and token-refresh failures;
+- `NetworkError` for connection and timeout failures;
+- `ApiError` for rejected HTTP requests;
+- `GraphQLError` for rejected GraphQL operations;
+- `ResponseError` for malformed responses;
+- `ReadOnlyError` for blocked state-changing operations.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m pytest
+python -m build
+```
+
+See the [API guide](docs/api.md) and [authentication guide](docs/authentication.md) for usage
+details. Development and release procedures are documented in
+[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/releasing.md](docs/releasing.md). Security issues
+should follow [SECURITY.md](SECURITY.md).
+
+`pynissan` is an independent community project and is not affiliated with Nissan.

pynissan-0.1.0/README.md

@@ -0,0 +1,157 @@
+# pynissan
+
+[![CI](https://github.com/bvdcode/nissan-connect-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/bvdcode/nissan-connect-sdk/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pynissan.svg)](https://pypi.org/project/pynissan/)
+[![Python](https://img.shields.io/pypi/pyversions/pynissan.svg)](https://pypi.org/project/pynissan/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`pynissan` is an independently maintained async Python client for MyNISSAN connected
+vehicle services. It provides a typed API for vehicle telemetry, charging, climate,
+remote commands, account data, and connected-service features.
+
+The client currently supports United States MyNISSAN accounts and includes Nissan Ariya
+telemetry and remote-control support.
+
+## Highlights
+
+- Fully async I/O built on `aiohttp`.
+- Typed, immutable response models and a `py.typed` marker.
+- Cached vehicle, battery, charging, climate, door, location, tire, and mileage data.
+- Charging, climate, lock, light, horn, engine, location, and status-refresh commands.
+- Climate and charge schedules, vehicle capabilities, alerts, maintenance, and history.
+- Automatic access-token refresh with a callback for persisting replacement tokens.
+- Static or refreshable request proof for protected service operations.
+- Read-only mode enabled by default for safe discovery and monitoring.
+- No dependency on Home Assistant.
+
+## Installation
+
+```bash
+python -m pip install pynissan
+```
+
+Python 3.12 or newer is required.
+
+## Quick start
+
+The caller owns the `aiohttp.ClientSession` and decides how credentials and reusable tokens
+are stored.
+
+```python
+from aiohttp import ClientSession
+
+from pynissan import Country, NissanClient, Tokens
+
+
+async def save_tokens(tokens: Tokens) -> None:
+    """Persist replacement tokens in the application's secure storage."""
+
+
+async def read_vehicle(email: str, password: str) -> None:
+    async with ClientSession() as session:
+        client = NissanClient(
+            session,
+            country=Country.US,
+            token_listener=save_tokens,
+        )
+        await client.async_authenticate(email, password)
+
+        vehicles = await client.async_get_vehicles()
+        if not vehicles:
+            return
+
+        status = await client.async_get_vehicle_status(vehicles[0].vin)
+        if status.battery is not None:
+            print(status.battery.level)
+            print(status.battery.is_charging)
+```
+
+Supply previously saved tokens to avoid signing in again:
+
+```python
+client = NissanClient(
+    session,
+    country=Country.US,
+    tokens=saved_tokens,
+    token_listener=save_tokens,
+)
+```
+
+The client refreshes expired tokens before a request and publishes the replacement token set
+through `token_listener`.
+
+Protected operations accept a `RequestProof` value or an async `RequestProofProvider`. The
+provider is called with `False` for a current value and with `True` when the service rejects a
+stale value.
+
+## Read-only safety
+
+`NissanClient` starts in read-only mode. Queries work normally, while methods that change
+vehicle or account state raise `ReadOnlyError` before any network request is sent.
+
+```python
+from pynissan import Country, NissanClient
+
+client = NissanClient(
+    session,
+    country=Country.US,
+    tokens=saved_tokens,
+    read_only=False,
+)
+```
+
+Enable write access only for an explicit user action. Remote commands return a typed request
+that can be polled until Nissan reports a terminal status.
+
+```python
+from pynissan import ClimateSettings, TemperatureUnit
+
+request = await client.async_start_climate(
+    vin,
+    ClimateSettings(72, TemperatureUnit.FAHRENHEIT),
+)
+result = await client.async_wait_for_service_request(vin, request)
+```
+
+## Charging state
+
+Battery status distinguishes the cable and charging states and includes the server-provided
+remaining charge time.
+
+```python
+battery = await client.async_get_vehicle_battery_status(vin)
+if battery is not None:
+    print(battery.level)
+    print(battery.is_plugged_in)
+    print(battery.is_charging)
+    print(battery.remaining_charge_time)
+```
+
+## Errors
+
+All package exceptions inherit from `NissanError`:
+
+- `AuthenticationError` for sign-in and token-refresh failures;
+- `NetworkError` for connection and timeout failures;
+- `ApiError` for rejected HTTP requests;
+- `GraphQLError` for rejected GraphQL operations;
+- `ResponseError` for malformed responses;
+- `ReadOnlyError` for blocked state-changing operations.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m pytest
+python -m build
+```
+
+See the [API guide](docs/api.md) and [authentication guide](docs/authentication.md) for usage
+details. Development and release procedures are documented in
+[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/releasing.md](docs/releasing.md). Security issues
+should follow [SECURITY.md](SECURITY.md).
+
+`pynissan` is an independent community project and is not affiliated with Nissan.

pynissan-0.1.0/SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Report package vulnerabilities through
+[GitHub private vulnerability reporting](https://github.com/bvdcode/nissan-connect-sdk/security/advisories/new).
+Do not open a public issue for a vulnerability that could expose account or vehicle access.
+
+Include the affected version, impact, reproduction steps, and a minimal test case when
+available. Do not include credentials, OAuth tokens, vehicle identifiers, or customer data.
+
+## Supported versions
+
+Security fixes are released for the latest minor version of `pynissan`.
+
+| Version | Supported |
+| --- | --- |
+| 0.1.x | Yes |

pynissan-0.1.0/docs/api.md

@@ -0,0 +1,81 @@
+# API guide
+
+The package exports `NissanClient`, `Country`, `Tokens`, `RequestProof`,
+`RequestProofProvider`, domain models, input models, enums, and exceptions from the
+`pynissan` namespace. Public objects include precise type hints and runtime docstrings.
+
+## Client lifecycle
+
+The caller owns the `aiohttp.ClientSession` and closes it after all client work is complete.
+One client represents one account and one country.
+
+```python
+from aiohttp import ClientSession
+
+from pynissan import Country, NissanClient
+
+
+async with ClientSession() as session:
+    client = NissanClient(session, country=Country.US)
+    await client.async_authenticate(email, password)
+    vehicles = await client.async_get_vehicles()
+```
+
+## Common reads
+
+| Method | Result |
+| --- | --- |
+| `async_get_vehicles()` | Vehicles associated with the account |
+| `async_get_vehicle_status()` | Combined cached status and telemetry |
+| `async_get_vehicle_battery_status()` | Battery level, cable state, charge state, range, and remaining time |
+| `async_get_vehicle_climate_status()` | Cached cabin climate state |
+| `async_get_vehicle_doors_status()` | Door and lock state |
+| `async_get_vehicle_location()` | Last reported vehicle location |
+| `async_get_vehicle_capabilities()` | Features reported for a vehicle |
+| `async_get_charge_schedules()` | Recurring charging schedules |
+| `async_get_climate_schedules()` | Recurring climate schedules |
+| `async_get_vehicle_service_history()` | Service history entries |
+
+Nullable service fields remain nullable in the returned models. Enum types with an
+`UNKNOWN_VALUE` member preserve future upstream values without mapping them to a known state.
+
+## Remote commands
+
+State-changing methods require `read_only=False` when constructing the client.
+
+| Method | Command |
+| --- | --- |
+| `async_start_climate()` / `async_stop_climate()` | Cabin climate |
+| `async_start_charge()` / `async_stop_charge()` | Charging |
+| `async_lock_doors()` / `async_unlock_doors()` | Door locks |
+| `async_flash_lights()` | Exterior lights |
+| `async_flash_lights_and_horn()` | Exterior lights and horn |
+| `async_start_engine()` / `async_stop_engine()` | Remote engine start |
+| `async_locate_vehicle()` | Vehicle location refresh |
+| `async_refresh_vehicle_status()` | Vehicle status refresh |
+
+Vehicle capabilities and account subscriptions determine whether a command is available.
+Protected operations also use the request proof configured on the client when the service
+requires it.
+Most commands return a `ServiceRequest`; pass it to `async_wait_for_service_request()` to wait
+for a terminal result.
+
+```python
+request = await client.async_lock_doors(vin)
+result = await client.async_wait_for_service_request(vin, request)
+```
+
+All polling helpers raise `TimeoutError` when their configured deadline expires. A nullable
+result therefore represents an upstream response, never a hidden polling timeout.
+
+## Read-only policy
+
+Read-only mode is enabled by default. A blocked mutation raises `ReadOnlyError` before sending
+a network request. Applications should create write-enabled clients only for explicit user
+actions.
+
+## Errors
+
+Catch `NissanError` for package-level handling, or use its specific subclasses:
+`AuthenticationError`, `NetworkError`, `ApiError`, `GraphQLError`, `ResponseError`, and
+`ReadOnlyError`.

pynissan-0.1.0/docs/authentication.md

@@ -0,0 +1,68 @@
+# Authentication and tokens
+
+`NissanClient` accepts MyNISSAN credentials only when `async_authenticate()` is called. The
+returned `Tokens` object contains the access, refresh, and optional ID tokens used by later
+requests.
+
+```python
+tokens = await client.async_authenticate(email, password)
+```
+
+Applications should store replacement tokens whenever the listener is called. The listener
+may be synchronous or asynchronous.
+
+```python
+from pynissan import Country, NissanClient, Tokens
+
+
+async def save_tokens(tokens: Tokens) -> None:
+    await token_store.save(tokens)
+
+
+client = NissanClient(
+    session,
+    country=Country.US,
+    tokens=await token_store.load(),
+    token_listener=save_tokens,
+    oauth_device_id=stored_device_id,
+)
+```
+
+The client refreshes expired access tokens before authenticated requests. Concurrent requests
+share one refresh operation, and `token_listener` receives the replacement token set.
+
+Persist `client.oauth_device_id` with the account record so a later client instance can reuse
+the same OAuth device identity. Treat credentials, tokens, and the device identifier as
+sensitive application data. Do not log or commit them.
+
+## Protected requests
+
+Account onboarding and some connected-service operations require current request proof.
+Supply either a static pair or an async provider when constructing the client.
+
+```python
+from pynissan import NissanClient, RequestProof
+
+client = NissanClient(
+    session,
+    tokens=tokens,
+    request_proof=RequestProof(api_attestation, device_status),
+)
+```
+
+For long-running applications, a provider can load or refresh the pair on demand:
+
+```python
+async def request_proof_provider(force_refresh: bool) -> RequestProof:
+    return await proof_store.load(force_refresh=force_refresh)
+
+
+client = NissanClient(
+    session,
+    tokens=tokens,
+    request_proof_provider=request_proof_provider,
+)
+```
+
+The provider receives `False` for a normal request and `True` after the service rejects the
+current proof. A static value and a provider cannot be supplied together.