Metadata-Version: 2.4
Name: hermers
Version: 0.1.0
Summary: Official Hermers SDK - REST + gRPC clients (API key auth)
Author: Aduki
License-Expression: MIT
Project-URL: Homepage, https://github.com/aduki-org/hermers-py
Project-URL: Repository, https://github.com/aduki-org/hermers-py
Project-URL: Documentation, https://aduki-org.github.io/hermers-py
Project-URL: Issues, https://github.com/aduki-org/hermers-py/issues
Keywords: hermes,hermers,sdk,rest,grpc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio
Requires-Dist: protobuf
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Dynamic: license-file

# hermers

Open-source **Python** client for Hermers with REST and native gRPC in **one package**.

The Hermers **server is private / proprietary**. This repository is the public SDK only and does
not include or publish server source.

| Client | Import | Default endpoint |
| --- | --- | --- |
| `Hermes` | `hermers` | `https://hermers.aduki.pro/v1` |
| `HermesGrpc` | `hermers` | `grpc.aduki.pro:443` |

## Requirements

- Python **3.11+**

## Install

```bash
pip install hermers
```

## Quickstart (REST)

```python
from hermers import Hermes

hermes = Hermes("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
me = hermes.ready()
print(me.tenant, me.user)

contacts = hermes.contacts.list({"limit": 50})
print(contacts["total"])
```

## Quickstart (gRPC)

```python
from hermers import HermesGrpc

client = HermesGrpc("hm_live_xxxxxxxxxxxxxxxxxxxxxxxx")
client.ready()
print(client.me.tenant, client.me.user)

mailboxes = client.mail.list_mailboxes()
print(len(mailboxes.items))
client.close()
```

For resource-by-resource examples, see `docs/rest/README.md` and `docs/grpc/README.md`.

## Authentication

**API key only**:

- REST: `Authorization: Key <key>`
- gRPC metadata: `authorization: Key <key>`

The SDK does not expose login, password, or JWT refresh helpers. Prefer `ready()` before the first
resource call. Callers never pass tenant/user hex for scoped resource methods because both clients
cache `whoami`.

## Resources

REST properties:

- `contacts`
- `mail`
- `keys`
- `user`
- `tenant`
- `calendar`
- `events`
- `feeds`
- `scheduling`

gRPC properties:

- `contacts`
- `mail`
- `feeds`
- `storage`
- `sync`
- `security`
- `spam`
- `tier`
- `usage`
- `session`

The clean top-level API stays available via `hermers.Hermes` / `hermers.HermesGrpc`, while the
implementation is organized under `hermers.rest.*` and `hermers.grpc.*`.

## Testing

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
# for live tests, set the API-key environment variable expected by the test suite
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

Without a live API key configured, the unit suites still run and the live REST/gRPC tests no-op.
Never commit secrets or local environment files.

## Docs

Developer docs live under `docs/` and publish with
**[mdBook](https://rust-lang.github.io/mdBook/)**.

The book source is assembled from `docs/` plus this repository `README.md` into `book/`, then
built into `site/` for GitHub Pages.

Requires `mdbook` on `PATH`.

```bash
make docs-prepare
make docs-build
make docs-check
make docs-serve
make docs
```

## License

MIT
