Metadata-Version: 2.5
Name: prefect-unirate
Version: 0.1.0
Summary: Prefect 3 integration for the UniRate currency-exchange API — a credentials block plus tasks for real-time rates, conversion, currencies, and VAT.
Project-URL: Homepage, https://github.com/UniRate-API/prefect-unirate
Project-URL: Repository, https://github.com/UniRate-API/prefect-unirate
Project-URL: Issues, https://github.com/UniRate-API/prefect-unirate/issues
Project-URL: Provider, https://unirateapi.com
Author: Unirate Team
License: MIT
License-File: LICENSE
Keywords: currency,data-engineering,exchange-rates,prefect,unirate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: prefect<4.0.0,>=3.0.0
Description-Content-Type: text/markdown

# prefect-unirate

[![PyPI](https://img.shields.io/pypi/v/prefect-unirate.svg)](https://pypi.org/project/prefect-unirate/)
[![Prefect](https://img.shields.io/badge/Prefect-3.x-026AF5?logo=prefect)](https://www.prefect.io/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Prefect 3 integration for **[UniRateAPI](https://unirateapi.com)** — real-time
currency exchange rates, conversion, currency lists, and VAT rates as
first-class Prefect tasks, wired up through a reusable credentials block.

## Install

```bash
pip install prefect-unirate
```

Requires `prefect >= 3.0.0` and Python 3.10+. Get a free API key at
<https://unirateapi.com>.

## Credentials

`UniRateCredentials` is a Prefect [`Block`](https://docs.prefect.io/latest/develop/blocks/)
that stores your API key (as a `SecretStr`) and builds a client.

Register the block type once, then save an instance you can reuse across flows:

```bash
prefect block register -m prefect_unirate
```

```python
from prefect_unirate import UniRateCredentials

UniRateCredentials(api_key="your-key").save("unirate")
```

Load it anywhere with `UniRateCredentials.load("unirate")`.

## Tasks

```python
from prefect import flow
from prefect_unirate import (
    UniRateCredentials,
    get_exchange_rate,
    convert_currency,
    list_currencies,
    get_vat_rates,
)


@flow
def fx() -> None:
    creds = UniRateCredentials.load("unirate")

    rate = get_exchange_rate(creds, "USD", "EUR")     # 0.92
    amount = convert_currency(creds, "EUR", 100, "USD")  # 92.5
    codes = list_currencies(creds)                    # ['USD', 'EUR', ...]
    vat = get_vat_rates(creds, "DE")                  # {'country': 'DE', ...}
```

| Task | Endpoint | Returns |
|------|----------|---------|
| `get_exchange_rate(creds, from_currency="USD", to_currency=None)` | `/api/rates` | `float`, or `{code: rate}` when `to_currency` is omitted |
| `convert_currency(creds, to_currency, amount=1, from_currency="USD")` | `/api/convert` | `float`, or `{code: amount}` |
| `list_currencies(creds)` | `/api/currencies` | `list[str]` |
| `get_vat_rates(creds, country=None)` | `/api/vat/rates` | `dict` |

Currency and country codes are uppercased automatically before being sent.

## Error handling

Every task raises a typed exception on failure (all subclass `UnirateError`):

| Status | Exception |
|--------|-----------|
| 400 | `InvalidDateError` |
| 401 | `AuthenticationError` |
| 403 | `APIError` (`status_code=403`) — endpoint requires a Pro subscription |
| 404 | `InvalidCurrencyError` |
| 429 | `RateLimitError` |
| 503 | `APIError` (`status_code=503`) |
| network/transport | `UnirateError` |

Historical endpoints are Pro-gated and return `403` on the free tier.

## Example flow

A complete runnable flow lives at
[`examples/example_flow.py`](examples/example_flow.py). It reads
`UNIRATE_API_KEY` from the environment.

## Testing

```bash
pip install -e ".[test]"
pytest
```

Tests run against a temporary Prefect database via `prefect_test_harness`, with
the HTTP layer mocked by `respx` — no network access and no real Prefect server.

## Status

`v0.1.0` — initial release. Credentials block + 4 tasks. 30+ mock tests.

<!-- unirate-ecosystem-footer:start -->
## Other UniRate clients

UniRate ships official client libraries and framework integrations across the
ecosystem. The repos below are all maintained under the
[UniRate-API](https://github.com/UniRate-API) org.

- **Languages:** [Python](https://github.com/UniRate-API/unirate-api-python) · [Node.js / TypeScript](https://github.com/UniRate-API/unirate-api-nodejs) · [Go](https://github.com/UniRate-API/unirate-api-go) · [Rust](https://github.com/UniRate-API/unirate-api-rust) · [Java](https://github.com/UniRate-API/unirate-api-java) · [Ruby](https://github.com/UniRate-API/unirate-api-ruby) · [PHP](https://github.com/UniRate-API/unirate-api-php) · [.NET](https://github.com/UniRate-API/unirate-api-dotnet) · [Swift](https://github.com/UniRate-API/unirate-api-swift)
- **Data / orchestration:** [Airflow](https://github.com/UniRate-API/airflow-provider-unirate) · [dbt](https://github.com/UniRate-API/dbt-unirate) · [LangChain](https://github.com/UniRate-API/langchain-unirate)
- **Web frameworks:** [FastAPI](https://github.com/UniRate-API/fastapi-unirate) · [Flask](https://github.com/UniRate-API/flask-unirate) · [Django / Wagtail](https://github.com/UniRate-API/wagtail-unirate) · [NestJS](https://github.com/UniRate-API/nestjs-unirate)
- **Workflow / no-code:** [n8n](https://github.com/UniRate-API/n8n-nodes-unirate) · [Google Sheets](https://github.com/UniRate-API/unirate-sheets) · [MCP server](https://github.com/UniRate-API/unirate-mcp)

Get a free API key at [unirateapi.com](https://unirateapi.com).
<!-- unirate-ecosystem-footer:end -->

## License

MIT.

## Links

- UniRate API docs: <https://unirateapi.com/docs>
- Prefect integrations: <https://docs.prefect.io/latest/integrations/>
- Issues: <https://github.com/UniRate-API/prefect-unirate/issues>
