Metadata-Version: 2.4
Name: teambattles-sdk
Version: 0.1.0
Summary: Official Python SDK for the TeamBattles public developer API.
Author: TeamBattles
License: MIT
Project-URL: Homepage, https://teambattles.gg
Project-URL: Documentation, https://teambattles.gg/docs
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: microsoft-kiota-abstractions>=1.0.0
Requires-Dist: microsoft-kiota-http>=1.0.0
Requires-Dist: microsoft-kiota-serialization-json>=1.0.0
Requires-Dist: microsoft-kiota-serialization-text>=1.0.0
Requires-Dist: microsoft-kiota-serialization-form>=1.0.0
Requires-Dist: microsoft-kiota-serialization-multipart>=1.0.0

# teambattles-sdk

Official Python SDK for the TeamBattles public developer API.

Auto-generated from the TeamBattles OpenAPI 3.1 specification with [Microsoft Kiota](https://learn.microsoft.com/en-us/openapi/kiota/). This README is generated by `pnpm sdk:docs` and regenerates on every API change - do not edit it by hand.

- Language: Python
- Registry: PyPI
- Maturity: Stable

## Install

```bash
pip install teambattles-sdk
```

## Dependencies

The generated client is a thin veneer over the shared Kiota runtime. This package depends on:

- `microsoft-kiota-abstractions`
- `microsoft-kiota-http`
- `microsoft-kiota-serialization-json`
- `microsoft-kiota-serialization-text`
- `microsoft-kiota-serialization-form`
- `microsoft-kiota-serialization-multipart`

## Create a client

Construct a client once with your API key. The factory wires a bearer-token authentication provider and points the client at the production base URL.

```python
import os
from teambattles_sdk import create_teambattles_client

client = create_teambattles_client(os.environ["TEAMBATTLES_API_KEY"])
```

## First call: list the authenticated user's matches

```python
# List the authenticated user's matches (requires matches.user_matches: read)
from teambattles_sdk.models import MatchesRequestBody

result = await client.user.matches.post(MatchesRequestBody(num_items=25))
for match in result.page or []:
    print(match.id, match.status)
```

## Authentication

Every request is authenticated with an API key sent as a bearer token:

```
Authorization: Bearer tb_<your-key>
```

Create and manage keys at [Settings > Developer](https://teambattles.gg/settings/developer). Keys carry granular permission scopes - listing the authenticated user's matches requires `matches.user_matches: read`.

Errors return a JSON body of the form `{ "error": "<machine_code>", "details": "<optional message>" }`. Treat the `error` machine code - not the `details` message - as the stable programmatic contract: branch on `error`, and use `details` only for human-readable context (it may be absent on auth and permission errors).

## Documentation

- API reference and guides: https://teambattles.gg/docs/developers
- SDKs overview: https://teambattles.gg/docs/sdks
- This SDK: https://teambattles.gg/docs/sdks/python
- Authentication: https://teambattles.gg/docs/developers/authentication

## License

MIT
