Metadata-Version: 2.4
Name: shamcash
Version: 1.1.5
Summary: Python client for the ShamCash API
Author-email: melchersman <melchersman@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Melchersman/shamcash
Project-URL: Documentation, https://shamcash-api.com
Project-URL: Repository, https://github.com/Melchersman/shamcash
Project-URL: Issues, https://github.com/Melchersman/shamcash/issues
Keywords: shamcash,sham cash,shamcash api,shamcashapi,payment,api,syria,wallet
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: backports.zoneinfo>=0.2.1; python_version < "3.9"
Requires-Dist: tzdata>=2024.1; platform_system == "Windows"
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: python-dotenv>=1.0; extra == "dev"
Dynamic: license-file

# shamcash

Python client for the ShamCash HTTP API.

## Installation

```bash
pip install shamcash
```

## Quick start

```python
from shamcash import ShamCashAPISync

with ShamCashAPISync(api_token="...") as client:
    account = client.list_accounts()[0]
    balances = client.get_balances(account.id)
```

## Async

```python
import asyncio

from shamcash import ShamCashAPI


async def main() -> None:
    async with ShamCashAPI(api_token="...") as client:
        account = (await client.list_accounts())[0]
        balances = await client.get_balances(account.id)
        transactions = await client.list_transactions(account.id, limit=20)


asyncio.run(main())
```

## Sync

```python
from shamcash import ShamCashAPISync

with ShamCashAPISync(api_token="...") as client:
    account = client.list_accounts()[0]
    balances = client.get_balances(account.id)
    transaction = client.get_transaction(account.id, 184627893)
```

## Errors

- API envelope codes map to typed exceptions such as `AuthInvalidError`, `AccountNotFoundError`, `SubscriptionUnavailableError`, and `RateLimitExceededError`.
- Transport failures raise `NetworkError`.
- Timeouts raise `RequestTimeoutError`.
- Invalid JSON or schema mismatches raise `ProtocolError`.

## Capabilities

- `list_accounts()`
- `get_account(account_id)`
- `get_balances(account_id)`
- `list_transactions(account_id, *, start_at=None, end_at=None, transaction_ids=None, coin_id=None, limit=None)`
- `get_transaction(account_id, transaction_id)`
- `fetch_json_envelope(method, path, params=None)`

## Models and typing

- Account, balance, and transaction payloads are exposed as typed dataclasses.
- Money fields use `Decimal`.
- Timestamps use timezone-aware UTC `datetime`.
- Naive ShamCash timestamps are interpreted as `Asia/Damascus` and normalized to UTC.

## Compatibility

- Python 3.8+
