Metadata-Version: 2.4
Name: openroam
Version: 0.1.0rc6
Summary: OpenRoam Partner API
Home-page: https://openroamhq.github.io/openroam-sdks/python/
Author: OpenRoam Support
Author-email: OpenRoam Support <support@openroam.com>
Project-URL: Homepage, https://openroamhq.github.io/openroam-sdks/python/
Project-URL: Changelog, https://openroamhq.github.io/openroam-sdks/changelog/
Keywords: OpenAPI,OpenAPI-Generator,OpenRoam Partner API
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3<3.0.0,>=2.7.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.11
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# OpenRoam SDK for Python

Official client for the OpenRoam Partner API: eSIMs, airtime, utility payments, gift cards, hotels and flights.
Python 3.11+.

## Install

```bash
pip install openroam==0.1.0-rc.6
```

> This is a **release candidate**: install it by its exact version, as above; a plain install does not pick it up. Before 1.0 the API can change between minor versions; every change is listed in the [changelog](https://openroamhq.github.io/openroam-sdks/changelog/).

## Quick start

```python
import os
from openroam import OpenRoam

openroam = OpenRoam(os.environ["OPENROAM_API_KEY"])  # or OpenRoam() with OPENROAM_API_KEY set

found = openroam.esims.search(country_code="JP")
quote = openroam.esims.quote({"currency": "USD", "items": items})
order = openroam.esims.order({"currency": "USD", "items": items})

openroam.esims.get_usage(iccid)
openroam.hotels.search({...})
```

Every product is an attribute of the client: `esims`, `airtime`, `utilities`, `gift_cards`, `hotels`, `flights`, plus `orders`,
`order_items`, `wallets`, `currencies`, `countries` and `mobile_networks`. Buying always reads `search`, `quote`, `order`; `get` fetches
one thing you own, `list_...` returns many, everything else starts with a verb. A path id is the first argument, a body is passed as it
is (a dict with the API's field names, or the model, such as `openroam.EsimOrderRequest`), and query parameters are keyword arguments.
Answers are models: `found.items`, `found.pagination`.

Options when you need them:

```python
openroam = OpenRoam(
    api_key="key",
    environment="sandbox",  # default "production"
    max_retries=3,          # default 0: no retries
    # base_url="https://..." to point anywhere else, for example a development host
)

openroam.esims.search(country_code="JP", timeout=10)  # every call takes a timeout, in seconds
```

## Orders are safe to repeat

An idempotency key means: if the same request arrives twice, OpenRoam makes one order, not two. `order()` creates a key for you on every call.
To stay safe even if *your own* program crashes and asks again, pass a UUID generated once and persisted for that purchase, for example
your order id if it is a UUID:

```python
openroam.esims.order(body, idempotency_key=my_order_id)
```

## Errors

A failed call raises an `OpenRoamError` with the error body of the API: `status`, `code` (branch on this), `name`, `message`, `request_id`
(keep it for support) and `details` (a list of dicts with `path`, `reason` and `message`). When no answer arrived (network error,
timeout), `status` is `None` and `__cause__` is the original error.

```python
from openroam import OpenRoam, OpenRoamError

try:
    openroam.esims.order(body)
except OpenRoamError as error:
    if error.code == 11002:
        ...  # the price rose above your maxPrice
    else:
        raise
```

## Lists and pages

Pagination depends on the method. `esims.search` accepts `page` and `limit` and returns `items` and `pagination`, while `orders.list`
returns `orders` and `pagination`. `esims.list_catalog` accepts `cursor` and `limit` and returns `items` and `next_cursor`; pass
`next_cursor` as `cursor` to fetch the next page. Some lists, such as `esims.list_compatible_devices`, return a plain list.

## Webhooks

```python
from openroam import verify_webhook, WebhookSignatureError

verify_webhook(
    secret=os.environ["OPENROAM_WEBHOOK_SECRET"],
    timestamp=headers["X-OpenRoam-Timestamp"],
    event_id=headers["X-OpenRoam-Event-Id"],
    signature=headers["X-OpenRoam-Signature"],
    raw_body=request_body,  # the body exactly as received, before JSON parsing
)  # raises WebhookSignatureError when invalid or older than 5 minutes
```

## Retries

Retries are off by default. Set `max_retries` to retry network errors, `429`, `502/503/504` and "still running" (`12002`) safely:
a `POST` is sent again only with its `Idempotency-Key`, the same key and the same body, and `order()` always has one.

```python
openroam = OpenRoam(api_key, max_retries=3)
```

The full behaviour: [Retries and idempotency](https://openroamhq.github.io/openroam-sdks/retries/). `enable_retries` and `new_idempotency_key` (in
`openroam.retry`) are also exported if you build your own requests.

## Good to know

- **Amounts** are `{ amount, currency }`. `price` is what OpenRoam charges you, `value` what your customer receives.
- Full API documentation: https://openroam.com (partner portal). Support: support@openroam.com.

The client is generated from the OpenRoam Partner API description, so it always matches the API; `webhooks`, `retry` and the errors are hand-written. MIT licensed.
