Metadata-Version: 2.4
Name: perkstar
Version: 0.1.0
Summary: Official Python client for the Perkstar REST API
Author-email: Perkstar <support@perkstar.co.uk>
License-Expression: MIT
Project-URL: Documentation, https://developers.perkstar.co.uk/sdks/python
Project-URL: Homepage, https://perkstar.co.uk
Project-URL: Changelog, https://developers.perkstar.co.uk/changelog
Keywords: perkstar,loyalty,wallet,pos,odoo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: ruff==0.16.0; extra == "dev"
Dynamic: license-file

# Perkstar Python SDK

Official synchronous Python client for the
[Perkstar REST API](https://developers.perkstar.co.uk). It is designed for
Odoo modules, POS middleware, scheduled data syncs, and backend services.

## Install

```bash
python -m pip install \
  https://dashboard.perkstar.co.uk/developer-downloads/perkstar-0.1.0-py3-none-any.whl
```

Python 3.9 or newer is supported. The package is ready for PyPI; until the
first public PyPI release, the versioned wheel above is the official download.

## Quickstart

```python
import os

from perkstar import Perkstar

with Perkstar(api_key=os.environ["PERKSTAR_API_KEY"]) as perkstar:
    context = perkstar.marketplace.ping()
    print(f"Connected to {context['data']['organization']['name']}")

    result = perkstar.marketplace.accrue(
        {
            "identifier": {"email": "alice@example.com"},
            "card_id": "card_123",
            "transaction": {
                "type": "STAMP",
                "external_transaction_id": "odoo-order-981",
            },
        }
    )
    print(result["enrollment"]["balance"])
```

## Reliability defaults

- Every POST receives a UUID `Idempotency-Key` automatically.
- 408, 429, and transient 5xx responses are retried with jitter.
- `Retry-After` is honoured.
- List endpoints expose a lazy cursor iterator.
- Typed exceptions retain the API error code and `X-Request-Id`.
- Webhook verification uses constant-time HMAC comparison and a five-minute
  replay window.

## Pagination

```python
for customer in perkstar.customers.list(limit=100):
    print(customer["email"])

# Buffer the full result only when the data set is known to be small.
customers = perkstar.customers.list(limit=100).all()
```

## Errors

```python
from perkstar import PerkstarError, PerkstarRateLimitError

try:
    perkstar.marketplace.ping()
except PerkstarRateLimitError as error:
    print("Retry in", error.retry_after, "seconds")
except PerkstarError as error:
    print(error.code, error.request_id)
```

## Webhooks

```python
from perkstar import verify_webhook_signature

event = verify_webhook_signature(
    raw_request_body,
    request.headers["X-Perkstar-Signature"],
    webhook_secret,
)
```

Always pass the raw body exactly as received. Parsing and re-serializing it
before verification changes the signed bytes.
