Metadata-Version: 2.5
Name: tolt
Version: 1.2.0
Summary: Python SDK for the Tolt Public API
Project-URL: Homepage, https://github.com/toltapp/tolt-python-sdk
Project-URL: Repository, https://github.com/toltapp/tolt-python-sdk
Project-URL: Issues, https://github.com/toltapp/tolt-python-sdk/issues
Author: Tolt
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: affiliate,api,referral,sdk,tolt
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.21.2
Requires-Dist: pydantic>=1.9.2
Requires-Dist: typing-extensions>=4.0.0
Description-Content-Type: text/markdown

# tolt

Python SDK for the Tolt API (v2), with sync and async clients. Run it on your server: it needs your secret API key. Requires Python 3.10 or newer.

## Install

```bash
pip install tolt
```

## Usage

```python
import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

partner = client.partners.get(id="part_8fKq2LmZx7RtYw3nVbHc5dPj").data

for customer in client.customers.list():
    print(customer.id)
```

Single-item calls return the API envelope, so read `.data`. `list` returns a pager: iterate it to walk every page, or read `.items` for one page.

Resources: `partners`, `customers`, `transactions`, `commissions`, `links`, `clicks`, `promotion_codes`, `programs`, `groups`, `flows`, `reports`, `embed_tokens`.

### Async

```python
import asyncio
import os
from tolt import AsyncToltApi

client = AsyncToltApi(token=os.environ["TOLT_API_KEY"])


async def main() -> None:
    async for partner in await client.partners.list():
        print(partner.id)


asyncio.run(main())
```

## Errors

```python
import httpx
from tolt import NotFoundError
from tolt.core.api_error import ApiError

try:
    client.partners.get(id="part_8fKq2LmZx7RtYw3nVbHc5dPj")
except NotFoundError as e:
    print(e.body.code)  # "not_found"
except ApiError as e:
    print(e.status_code, e.body)
except httpx.TimeoutException:
    ...  # no response within the timeout
```

Every API error extends `ApiError`. Timeouts raise httpx's `TimeoutException`. Read `e.status_code` and `e.body` rather than `str(e)`, which starts with the response headers.

## Retries and timeouts

Failed requests (408, 409, 429, 5xx and dropped connections) are retried twice with backoff. Calls that create something (every `create`, and `transactions.rerun_flows`) are never retried, so a server error can't create a duplicate. Override per client or per call:

```python
client = ToltApi(token=os.environ["TOLT_API_KEY"], max_retries=3, timeout=30)

client.partners.get(id="part_8fKq2LmZx7RtYw3nVbHc5dPj", request_options={"timeout": 5})
```

The client talks to `https://platform.tolt.com` by default. Pass `base_url` to point it elsewhere.

## Type checking

The package ships `py.typed`. With mypy, annotate sub-clients you pass around (`partners: PartnersClient = client.partners`), since mypy reads the client's sub-client properties as untyped. Pyright infers them.

## Development

`src/tolt/` is generated by [Fern](https://buildwithfern.com) from the API's OpenAPI spec in [toltapp/tolt-sdks](https://github.com/toltapp/tolt-sdks), which opens a pull request here when the spec changes. Don't edit it by hand.

```bash
pip install -e . pytest mypy
pytest tests
mypy src/tolt --exclude src/tolt/tests
```
